openapi: 3.1.0
info:
  title: Brand Conversions API
  version: v11
  description: "Submit conversion events (sales, leads, subscriptions) to be reported and attributed to partners. \nThis API supports high-level order data and detailed item-level reporting.\n"
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/Conversions:
    post:
      operationId: createConversion
      tags:
      - Conversions
      summary: Create a conversion
      description: "Submit a conversion event. Requires at least one attribution key (e.g., ClickId, CustomerId), \nevent date, campaign ID, and order ID.\n"
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
        description: "The details of the conversion event.\n\n**Additional required parameters** not captured in the `required` list below:\n- One of `EventTypeId` or `EventTypeCode` is required (event identifier).\n- One of `ClickId`, `CustomerId`, or `CustomProfileId` 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."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionResponse'
        '400':
          description: Bad Request - Invalid parameters provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Status:
                    type: string
                    description: Indicates that the request failed.
                    example: ERROR
                  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.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    ConversionRequest:
      type: object
      required:
      - EventDate
      - CampaignId
      - OrderId
      properties:
        EventTypeId:
          type: integer
          description: Unique identifier for the event type. Required if EventTypeCode is not provided.
          example: '8180'
        EventTypeCode:
          type: string
          description: Configurable string identifying the event type. Required if EventTypeId is not provided.
          example: ACME_SALE
        EventDate:
          type: string
          format: date-time
          description: Time and date of conversion in ISO 8601 format, or NOW.
          example: '2023-02-15T22:55:32-08:00'
        CampaignId:
          type: integer
          description: Unique identifier for the program.
          example: '3641'
        OrderId:
          type: string
          description: Your unique identifier for the order.
          example: '9217374917471'
        ClickId:
          type: string
          description: impact.com generated click identifier.
          example: QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0
        CustomerId:
          type: string
          description: Non-identifying unique identifier for the customer.
          example: BCZ2WVSH674563PDPYOTM3AXDQ
        CustomProfileId:
          type: string
          description: Unique identifier used to identify a visitor (e.g., cookies).
          example: a1b2c3d4e5f6
        OrderPromoCode:
          type: string
          description: Promo code used for the order.
          example: 10OFF-ROCKET
        CustomerEmail:
          type: string
          description: Customer email (hashed or plain text).
          example: customer@gmail.com
        IpAddress:
          type: string
          description: IP address of the customer.
          example: 72.194.216.61
        CurrencyCode:
          type: string
          description: Three-letter ISO 4217 alpha code.
          example: USD
        OrderDiscount:
          type: number
          format: decimal
          example: '5'
          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.
          example: 95.0
        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.
          example: 5.0
        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.
          example: 8.0
        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.
          example: 30.0
        PaymentType:
          type: string
          description: This method of payment used for this conversion (e.g. Credit).
          example: CREDIT_CARD
        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.
          example: false
        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.
          example: NEW
        CustomerCity:
          type: string
          description: City of the customer, such as Santa Barbara.
          example: Santa Barbara
        CustomerPostCode:
          type: string
          description: Postal (or "ZIP") code of the customer, such as 93101.
          example: '93101'
        CustomerCountry:
          type: string
          description: Country of the customer, such as USA.
          example: USA
        CustomerRegion:
          type: string
          description: Region of the customer, such as AMER.
          example: AMER
        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.
          example: 10OFF-ACME
        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.
          example: Tennis
        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.
          example: ACME-MPN-101
        ItemBrand[i]:
          type: string
          description: Brand name for the product referenced. Can also be automatically pulled if a product catalog has been uploaded.
          example: Acme
        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).
          example: 1.0
        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.
          example: 5.0
        ItemDeliveryType[i]:
          type: string
          description: Type of delivery method specified for this item (e.g. INSTORE).
          example: INSTORE
        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.
          example: true
        UserAgent:
          type: string
          description: User agent of the customer, used to provide device reporting.
          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
        DeviceMfr:
          type: string
          description: Mobile device's manufacturer. Pass `android.os.Build.MANUFACTURER` on Android or `"Apple"` on iOS.
          example: Apple
        DeviceModel:
          type: string
          description: Mobile device's model. Pass `android.os.Build.MODEL` on Android or the value from `systemInfo.machine` on iOS.
          example: iPhone 15
        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.
          example: 12345
        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.
          example: com.acme.app
        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}.
          example: clickid=QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0
        AppVer:
          type: string
          description: Version of the mobile app. Only for mobile conversions.
          example: 1.2.3
        LocationId:
          type: string
          description: Primarily used for accommodations, this is the unique identifier for the location specified in this conversion.
          example: LOC-12345
        LocationName:
          type: string
          description: Primarily used for accommodations, this is the name for the location specified in this conversion.
          example: Acme Resort Santa Barbara
        LocationType:
          type: string
          description: Primarily used for accommodations, this is the category for the location specified in this conversion.
          example: HOTEL
        Note:
          type: string
          description: General field used to pass information for event-level reporting purposes.
          example: Customer confirmed delivery.
        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.
          example: DEFAULT
        Text1–Text50:
          type: string
          description: General text field that accepts strings of any text data you want to send. Appears in your reports. There are 50 of these fields, from Text1 to Text50.
          example: text1value
        Numeric1:
          type: number
          description: General numeral field that accepts any money or financial numeric data you want to send. Appears in your reports.
          example: 100.5
        Money1:
          type: number
          description: General money field that accepts any monetary numeric data you want to send. Appears in your reports.
          example: 50.0
        Numeric2:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 20.0
        Numeric3:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 30.0
        Numeric4:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 40.0
        Numeric5:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 50.0
        Numeric6:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 60.0
        Numeric7:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 70.0
        Numeric8:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 80.0
        Numeric9:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 90.0
        Numeric10:
          type: number
          description: General numeral field that accepts strings of any numeric data you want to send. Appears in your reports.
          example: 100.0
        Money2:
          type: number
          description: General numeral field that accepts strings of any money or financial data you want to send. Appears in your reports.
          example: 50.0
        Money3:
          type: number
          description: General numeral field that accepts strings of any money or financial data you want to send. Appears in your reports.
          example: 75.0
        Date1:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-03-28'
        Date2:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-05-21T07:25:00Z'
        Date3:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-03-28'
        Date4:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-05-21T07:25:00Z'
        Date5:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-03-28'
        Date6:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-05-21T07:25:00Z'
        Date7:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-03-28'
        Date8:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-05-21T07:25:00Z'
        Date9:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-03-28'
        Date10:
          type: string
          description: Field that accepts a date string, for example "2026-03-28", or a datetime string, for example "2026-05-21T07:25:00Z". Appears in your reports.
          example: '2026-05-21T07:25:00Z'
    ConversionResponse:
      type: object
      properties:
        Status:
          type: string
          description: Indicates whether the conversion was successfully queued.
          example: QUEUED
        QueuedUri:
          type: string
          format: uri-reference
          description: The unique reference to the queued submission.
          example: /Advertisers/<AccountSID>/APISubmissions/<SubmissionID>
