# Conversions

## Submit a Conversion Event

> Submits a conversion event for tracking and attribution. A minimum set of parameters including an event identifier, an attribution key, event date, campaign ID, and order ID is required.\
> It is highly recommended to provide as much data as possible for accurate attribution and payout calculation.

```json
{"openapi":"3.1.0","info":{"title":"Brand API - Conversions","version":"v14"},"servers":[{"url":"https://api.impact.com"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"ConversionPayload":{"type":"object","required":["CampaignId","EventDate","OrderId"],"properties":{"EventTypeId":{"type":"integer","description":"Unique identifier for the event type (action tracker)."},"EventTypeCode":{"type":"string","description":"Configurable string code for the event type."},"ClickId":{"type":"string","description":"Unique identifier of a referring click."},"CustomerId":{"type":"string","description":"Your unique, non-PII identifier for the customer."},"CustomProfileId":{"type":"string","description":"Unique identifier for a visitor on your website."},"OrderPromoCode":{"type":"string","description":"Promo code used for the order. Used for attribution if assigned to a specific partner."},"UniqueUrl":{"type":"string","format":"uri","description":"Unique URL of a partner that referred the conversion."},"GoogAId":{"type":"string","description":"Google Advertising ID."},"AppleIfa":{"type":"string","description":"Apple ID for Advertising (IDFA)."},"AppleIfv":{"type":"string","description":"Apple ID for Vendors (IDFV)."},"MediaId":{"type":"integer","description":"Force attribution to a specific partner ID. Use with caution."},"SubId1":{"type":"string","maxLength":255,"description":"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":{"type":"string","maxLength":255,"description":"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 fields typically used by partners to segment their traffic."},"SubId3":{"type":"string","maxLength":255,"description":"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":{"type":"string","maxLength":255,"description":"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."},"PhoneNumber":{"type":"string","description":"Phone number called for call tracking conversions."},"CallerId":{"type":"string","description":"Unique identifier of the customer in call tracking conversions."},"CountryCode":{"type":"string","description":"Primarily used for conversions over the phone, this is the ISO 3166-1 alpha-2 two-letter country code of the number called by the customer."},"IpAddress":{"type":"string","description":"Customer's IP address. Used for fraud detection and install attribution."},"EventDate":{"type":"string","format":"date-time","description":"Timestamp of when the conversion occurred (ISO 8601)."},"CampaignId":{"type":"integer","description":"Unique identifier for your program/campaign."},"OrderId":{"type":"string","description":"Your unique identifier for the order."},"CustomerEmail":{"type":"string","format":"email","description":"Customer's email, can be sent in plain text or SHA1 hashed."},"CustomerStatus":{"type":"string","description":"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."},"CustomerCity":{"type":"string","description":"City of the customer, such as Santa Barbara."},"CustomerPostCode":{"type":"string","description":"Postal (or \"ZIP\") code of the customer, such as 93101."},"CustomerCountry":{"type":"string","description":"Country of the customer, such as USA."},"CustomerRegion":{"type":"string","description":"Region of the customer, such as AMER."},"OrderDiscount":{"type":"number","format":"decimal","description":"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":{"type":"number","format":"decimal","description":"Used when reporting conversions at the order-level (i.e., no item reporting). 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":{"type":"number","format":"decimal","description":"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":{"type":"number","format":"decimal","description":"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":{"type":"number","format":"decimal","description":"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."},"OrderDiscountRate":{"type":"number","format":"decimal","description":"The discount rate (%) applied to the order."},"PaymentType":{"type":"string","description":"This method of payment used for this conversion (e.g. Credit)."},"GiftPurchase":{"type":"boolean","description":"If you're tracking gift purchases, you can submit true to mark the order in the conversion as a gift purchase. Submit false if the order isn't a gift purchase."},"CurrencyCode":{"type":"string","description":"3-character ISO 4217 currency code of the purchase."},"Amount":{"type":"number","format":"decimal","description":"This is the total order sale amount made on an item or order level of the conversion."},"ItemSku[i]":{"type":"string","description":"SKU for the item (e.g., ItemSku1, ItemSku2)."},"ItemPromoCode[i]":{"type":"string","description":"Promotional code applied to the item for the order. Note that this parameter does not work with unique tracking codes setup for particular partners."},"ItemName[i]":{"type":"string","description":"The name for the product referenced. Can also be automatically appended through uploading a product catalog."},"ItemCategory[i]":{"type":"string","description":"Category of the item."},"ItemSubCategory[i]":{"type":"string","description":"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]":{"type":"string","description":"Manufacturer part number (MPN) for the product referenced. Can also be automatically pulled if a product catalog has been uploaded."},"ItemBrand[i]":{"type":"string","description":"Brand name for the product referenced. Can also be automatically pulled if a product catalog has been uploaded."},"ItemQuantity[i]":{"type":"integer","description":"Number of units for this line item."},"ItemPrice[i]":{"type":"number","format":"decimal","description":"Unit price for the item. Do not send if ItemSubTotal[i] is passed."},"ItemSubTotal[i]":{"type":"number","format":"decimal","description":"Total price for the line item. Do not send if ItemPrice[i] is passed."},"ItemDiscount[i]":{"type":"number","format":"decimal","description":"Discount applied to each item purchased of this type (not to the entire line item)."},"ItemDiscountRate[i]":{"type":"number","format":"decimal","description":"The discount rate (%) applied to each item purchased."},"ItemTotalDiscount[i]":{"type":"number","format":"decimal","description":"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."},"ItemDeliveryType[i]":{"type":"string","description":"Type of delivery method specified for this item (e.g. INSTORE)."},"UserAgent":{"type":"string","description":"User agent of the customer, used to provide device reporting."},"DeviceMfr":{"type":"string","description":"Mobile device's manufacturer. Pass `android.os.Build.MANUFACTURER` on Android or `\"Apple\"` on iOS."},"DeviceModel":{"type":"string","description":"Mobile device's model. Pass `android.os.Build.MODEL` on Android or the value from `systemInfo.machine` on iOS."},"PropertyId":{"type":"integer","description":"For mobile app conversions, this value is the \"System App ID\" of your app in impact.com. Found in Settings → Mobile Apps."},"AppPackage":{"type":"string","description":"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":{"type":"string","description":"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}."},"AppVer":{"type":"string","description":"Version of the mobile app. Only for mobile conversions."},"LocationId":{"type":"string","description":"Primarily used for accommodations, this is the unique identifier for the location specified in this conversion."},"LocationName":{"type":"string","description":"Primarily used for accommodations, this is the name for the location specified in this conversion."},"LocationType":{"type":"string","description":"Primarily used for accommodations, this is the category for the location specified in this conversion."},"TrackingConsent":{"type":"boolean","description":"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."},"Note":{"type":"string","description":"General field used to pass information for event-level reporting purposes.","maxLength":255},"DispositionCode":{"type":"string","description":"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."},"Text1":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text2":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text3":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text4":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text5":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text6":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text7":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text8":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text9":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Text10":{"type":"string","maxLength":64,"description":"General text field that accepts strings of any text data you want to send. Appears in your reports."},"Numeric1":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric2":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric3":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric4":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric5":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric6":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric7":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric8":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric9":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Numeric10":{"type":"number","format":"decimal","description":"General numeral field that accepts any numeric data you want to send. Appears in your reports."},"Money1":{"type":"number","format":"decimal","description":"General money field that accepts any monetary numeric data you want to send. Appears in your reports."},"Money2":{"type":"number","format":"decimal","description":"General money field that accepts any monetary numeric data you want to send. Appears in your reports."},"Money3":{"type":"number","format":"decimal","description":"General money field that accepts any monetary numeric data you want to send. Appears in your reports."},"Date1":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date2":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date3":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date4":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date5":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date6":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date7":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date8":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date9":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."},"Date10":{"type":"string","format":"date-time","description":"General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports."}}}}},"paths":{"/Advertisers/{AccountSID}/Conversions":{"post":{"summary":"Submit a Conversion Event","description":"Submits a conversion event for tracking and attribution. A minimum set of parameters including an event identifier, an attribution key, event date, campaign ID, and order ID is required.\nIt is highly recommended to provide as much data as possible for accurate attribution and payout calculation.","operationId":"submitConversion","tags":["Conversions"],"parameters":[{"name":"AccountSID","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The details of the conversion event.\n\n**Additional required parameters** not captured in the `required` list below:\n- One of `ActionTrackerId`, `EventTypeId`, or `EventTypeCode` is required (event identifier).\n- One of `ClickId`, `CustomerId`, `CustomProfileId`, `CustomClickId`, `PromoCode`, `MediaPartnerId`, `UniqueUrl`, `CallerId`, `GoogAId`, `AndroidId`, `AppleIfa`, or `AppleIfv` is required (attribution key).\n\n**Note on conditional requirements:** Many parameters listed below as *optional* are conditionally required based on what else you submit. For example:\n- Item-level fields (`ItemSku[i]`, `ItemQuantity[i]`, `ItemPrice[i]`, `ItemSubTotal[i]`, etc.) become required when reporting at the item level.\n- `CurrencyCode` is required when monetary fields are provided.\n- Mobile-app fields (`AppleIfa`, `GoogAId`, `AppPackage`, `AppInstallRef`, `PropertyId`) are required for mobile-app install attribution.\n- Call-tracking fields (`PhoneNumber`, `CallerId`, `CountryCode`) are required for call-tracking conversions.\n\nSee each field's description for specific conditional requirements.","required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ConversionPayload"}}}},"responses":{"200":{"description":"The conversion event has been successfully queued for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"Status":{"type":"string","description":"Indicates whether the conversion was successfully queued."},"QueuedUri":{"type":"string","format":"uri-reference","description":"The unique reference to the queued submission."}}}}}},"400":{"description":"Bad Request. The request was invalid, likely due to missing required fields or incorrect data formats.","content":{"application/json":{"schema":{"type":"object","properties":{"Status":{"type":"string","description":"Indicates that the request failed."},"errors":{"type":"array","description":"One or more validation errors describing what was wrong with the request.","items":{"type":"object","properties":{"field":{"type":"string","description":"The name of the field that caused the error."},"level":{"type":"string","description":"The severity of the error."},"message":{"type":"string","description":"A human-readable error message."}}}}}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.impact.com/brand-api-reference/reference/conversions/conversions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.