openapi: 3.1.0
info:
  title: Brand API - Actions
  version: v11
  description: |
    Manage conversion events (actions) credited to partners. This includes
    viewing action details, modifying individual items, reversing actions, and
    tracking the history of modifications via Action Updates.
servers:
  - url: https://api.impact.com
security:
  - basicAuth: []
paths:
  /Advertisers/{AccountSID}/Actions:
    get:
      operationId: listActions
      tags:
        - Actions
      summary: List all actions
      description: Returns a list of the actions your campaign has recorded. Actions are returned by creation date, with the most recently created actions appearing first.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
          example: IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1
        - name: CampaignId
          in: query
          required: true
          description: The ID of the campaign (program) to list actions for.
          schema:
            type: string
          example: "1000"
        - name: State
          in: query
          description: Filters actions based on their current state.
          schema:
            type: string
            enum:
              - PENDING
              - APPROVED
              - REVERSED
          example: PENDING
        - name: StartDate
          in: query
          description: |
            Filters for actions with a last updated date on or after this value (ISO 8601 with time component).
            Must be used together with EndDate. Cannot be more than 3 years in the past, and the range with EndDate cannot exceed 45 days.
          schema:
            type: string
            format: date-time
          example: "2024-01-01T00:00:00Z"
        - name: EndDate
          in: query
          description: |
            Filters for actions with a last updated date on or before this value (ISO 8601 with time component).
            Must be used together with StartDate.
          schema:
            type: string
            format: date-time
          example: "2024-01-31T23:59:59Z"
      responses:
        "200":
          description: An array of action objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Actions:
                    type: array
                    items:
                      $ref: "#/components/schemas/Action"

    put:
      operationId: updateAction
      tags:
        - Actions
      summary: Update an action or item
      description: |
        Updates the specified action by setting the values of the parameters passed.
        Use this endpoint to update high-level action details such as `CustomerStatus`.

        The action can be identified either by `ActionId`, or by the combination of `ActionTrackerId` and `OrderId`.

        Note: impact.com allows a maximum of 1,000 modifications per action.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ActionId:
                  type: string
                  description: Unique identifier for the action. Required unless using ActionTrackerId and OrderId together.
                  example: "1000.4636.158133"
                ActionTrackerId:
                  type: integer
                  description: Unique identifier for the action tracker (event type). Required with OrderId if ActionId is not used.
                  example: 2240
                OrderId:
                  type: string
                  description: Your unique order identifier. Required with ActionTrackerId if ActionId is not used.
                  example: "9217374917472"
                DispositionCode:
                  type: string
                  description: Submit `ORDER_UPDATE` as the default value for updating an action. Custom disposition codes may also be used if configured.
                  default: ORDER_UPDATE
                  example: ORDER_UPDATE
                CustomerStatus:
                  type: string
                  description: A new custom status for the customer associated with the action (e.g., `NEW`, `EXISTING`).
                  example: NEW
                Sku:
                  type: string
                  description: The SKU of the line item to update. For bulk updates use indexed params (Sku, Sku2, Sku3, etc.).
                  example: "12345"
                Quantity:
                  type: integer
                  description: The new absolute quantity for the item. For bulk updates use indexed params (Quantity, Quantity2, etc.).
                  example: 2
                Amount:
                  type: number
                  description: The new total sale amount for the order or item. Setting to 0 on a tracked action with a non-zero amount will reverse the action.
                  example: 19.99
                Reason:
                  type: string
                  description: |
                    Required. A valid reason code for the modification. Default reason codes:
                    `ORDER_UPDATE`, `ITEM_RETURNED`, `CONS_FRAUD`, `CONS_ERROR`, `ORDER_ERROR`,
                    `PUB_ACT_DISPUTE`, `ADV_ACT_DISPUTE`, `NOT_COMPLIANCE_TERMS`,
                    `ITEM_OUT_OF_STOCK`, `TEST_ACTION`, `PARTNER_NOT_ACTIVE`,
                    `CREDITED_DIFFERENT_MP`, `OTHER`.
                  example: ORDER_UPDATE
      responses:
        "200":
          description: Request queued successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueuedResponse"

    delete:
      operationId: reverseAction
      tags:
        - Actions
      summary: Reverse an action
      description: |
        Reverses an action, cancelling any pending payouts to partners.

        The action can be identified either by `ActionId`, or by the combination of `ActionTrackerId` and `OrderId`.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - DispositionCode
              properties:
                ActionId:
                  type: string
                  description: Unique identifier for the action to reverse. Required unless using ActionTrackerId and OrderId together.
                  example: "1000.4636.158133"
                ActionTrackerId:
                  type: integer
                  description: Unique identifier for the action tracker (event type). Required with OrderId if ActionId is not used.
                  example: 2240
                OrderId:
                  type: string
                  description: Your unique order identifier. Required with ActionTrackerId if ActionId is not used.
                  example: "9217374917472"
                DispositionCode:
                  type: string
                  description: Required. A valid code explaining the reason for the reversal.
                  enum:
                    - REJECTED
                    - CONS_INFO_INVALID
                    - CONS_ERROR
                    - CONS_FRAUD
                    - ITEM_RETURNED
                    - ITEM_OUT_OF_STOCK
                    - ORDER_ERROR
                    - PUB_ACT_DISPUTE
                    - NOT_COMPLIANCE_TERMS
                    - MP_RETURNED
                    - OTHER
                    - CREDITED_DIFFERENT_MP
                    - ADV_ACT_DISPUTE
                    - TEST_ACTION
                  example: ITEM_RETURNED
      responses:
        "200":
          description: Reversal queued successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueuedResponse"

  /Advertisers/{AccountSID}/Actions/{ActionId}:
    get:
      operationId: getActionById
      tags:
        - Actions
      summary: Retrieve an action
      description: Retrieves the details of an existing action using its unique ActionId.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
        - name: ActionId
          in: path
          required: true
          description: The unique impact.com identifier for the action.
          schema:
            type: string
          example: "1000.4636.158133"
      responses:
        "200":
          description: Returns an action object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"

  /Advertisers/{AccountSID}/Actions/{ActionId}/Items:
    get:
      operationId: listActionItems
      tags:
        - Actions
      summary: List all items for an action
      description: Returns a list of the items within the specified action. The items are returned in the order they were originally recorded. All actions contain at least one item.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
        - name: ActionId
          in: path
          required: true
          description: The unique impact.com identifier for the action.
          schema:
            type: string
          example: "1000.4636.158133"
      responses:
        "200":
          description: An array of action item objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ActionItems:
                    type: array
                    items:
                      $ref: "#/components/schemas/ActionItem"

  /Advertisers/{AccountSID}/Actions/{ActionId}/Items/{Sku}:
    get:
      operationId: getActionItemBySku
      tags:
        - Actions
      summary: Retrieve an item from an action
      description: Retrieves the details of a specific line item within an action, identified by ActionId and SKU.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
        - name: ActionId
          in: path
          required: true
          description: The unique impact.com identifier for the action.
          schema:
            type: string
          example: "1000.4636.158133"
        - name: Sku
          in: path
          required: true
          description: The SKU or product identifier for the item.
          schema:
            type: string
          example: "12345"
      responses:
        "200":
          description: Returns an action item object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionItem"

  /Advertisers/{AccountSID}/ActionUpdates:
    get:
      operationId: listActionUpdates
      tags:
        - Action Updates
      summary: List all action updates
      description: |
        Returns a list of action updates (a changelog of modifications) for the campaign.
        Action updates are returned by creation date, with the most recently created updates appearing first.

        The recommended approach is to filter by `StartDate` and `EndDate` to retrieve updates within a specific range.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
        - name: CampaignId
          in: query
          required: true
          description: The ID of the campaign to list action updates for.
          schema:
            type: integer
          example: 1000
        - name: StartDate
          in: query
          description: |
            Filters for updates with an UpdateDate on or after this value (ISO 8601 with time component).
            Must be used together with EndDate. Cannot be more than 3 years in the past, and the range cannot exceed 45 days.
          schema:
            type: string
            format: date-time
          example: "2024-01-01T00:00:00Z"
        - name: EndDate
          in: query
          description: |
            Filters for updates with an UpdateDate on or before this value (ISO 8601 with time component).
            Must be used together with StartDate.
          schema:
            type: string
            format: date-time
          example: "2024-01-31T23:59:59Z"
      responses:
        "200":
          description: An array of action update objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ActionUpdates:
                    type: array
                    items:
                      $ref: "#/components/schemas/ActionUpdate"

  /Advertisers/{AccountSID}/ActionUpdates/{ActionUpdateId}:
    get:
      operationId: getActionUpdateById
      tags:
        - Action Updates
      summary: Retrieve an action update
      description: Retrieves the details for a specific update record using its unique ActionUpdateId.
      parameters:
        - name: AccountSID
          in: path
          required: true
          description: Your unique account identifier.
          schema:
            type: string
        - name: ActionUpdateId
          in: path
          required: true
          description: The unique identifier for the action update, obtainable from the list endpoint.
          schema:
            type: string
          example: "1000.4636.158133.95095059"
      responses:
        "200":
          description: Returns an action update object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionUpdate"

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  schemas:
    Action:
      type: object
      description: Represents a conversion event credited to a partner.
      properties:
        Id:
          type: string
          description: Unique impact.com identifier for the action.
          example: "1000.4636.158133"
        CampaignId:
          type: integer
          description: Unique identifier for the campaign (program) this action belongs to.
          example: 1000
        CampaignName:
          type: string
          description: Display name of the campaign.
          example: "Acme Campaign"
        ActionTrackerId:
          type: integer
          description: Unique identifier for the action tracker (event type) that recorded this action.
          example: 2240
        ActionTrackerName:
          type: string
          description: Display name of the action tracker (event type).
          example: "Sale"
        MediaPartnerId:
          type: integer
          description: Unique identifier for the partner credited for this action.
          example: 10000
        MediaPartnerName:
          type: string
          description: Display name of the credited partner.
          example: "Acme Partner"
        State:
          type: string
          description: |
            Current state of the action.
            - `PENDING`: Awaiting locking date or manual approval. Actions that have been modified also carry this state.
            - `APPROVED`: Reached its locking date or was manually approved. Will pay out the partner. No further modifications permitted.
            - `REVERSED`: Was reversed and will not pay out the partner.
          enum:
            - PENDING
            - APPROVED
            - REVERSED
          example: "PENDING"
        AdId:
          type: integer
          description: Unique identifier for the ad creative that drove the winning click.
          example: 506720
        Payout:
          type: number
          description: Commission amount to be paid to the partner, in the currency specified by the `Currency` field.
          example: 0.88
        Amount:
          type: number
          description: Revenue amount associated with the action (sale amount), in the currency specified by the `Currency` field.
          example: 21.99
        Currency:
          type: string
          description: Three-letter ISO 4217 currency code for monetary values in this action.
          example: "USD"
        EventDate:
          type: string
          format: date-time
          description: Timestamp of when the conversion event occurred.
          example: "2020-09-10T10:42:38-07:00"
        Oid:
          type: string
          description: Your unique identifier for the order associated with this action.
          example: "9217374917472"
        CustomerId:
          type: string
          description: Your unique, non-PII identifier for the customer who made the conversion.
          example: "BCZ2WVSH674563PDPYOTM3AXDQ"
        Uri:
          type: string
          description: Unique URI reference to this action object.
          example: "/Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/Actions/1000.4636.158133"

    ActionItem:
      type: object
      description: Represents a single line item within an action.
      properties:
        Sku:
          type: string
          description: Stock-keeping unit (SKU) or product identifier for the item.
          example: "12345"
        ItemName:
          type: string
          description: Display name of the product.
          example: "Acme Tennis Balls (One Dozen)"
        Category:
          type: string
          description: Product category for the item.
          example: "Sports"
        Quantity:
          type: string
          description: Number of units of this product in the order.
          example: "2"
        SaleAmount:
          type: string
          description: Revenue amount for this line item.
          example: "19.27"
        Payout:
          type: number
          description: Commission amount for this line item.
          example: 0.77
        Uri:
          type: string
          description: Unique URI reference to this action item object.
          example: "/Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/Actions/1000.4636.158133/Items/12345"

    ActionUpdate:
      type: object
      description: Represents a single modification event in an action's lifecycle. Acts as a changelog entry.
      properties:
        Id:
          type: string
          description: Unique identifier for this action update record.
          example: "1000.4636.158133.95095059"
        ActionId:
          type: string
          description: Unique identifier for the parent action that was updated.
          example: "1000.4636.158133"
        State:
          type: string
          description: The state of the action at the time of this update.
          enum:
            - PENDING
            - APPROVED
            - REVERSED
          example: "PENDING"
        DeltaPayout:
          type: number
          description: The change in the Payout value recorded by this update.
          example: 0.88
        DeltaAmount:
          type: number
          description: The change in the Amount (sale amount) value recorded by this update.
          example: 21.99
        UpdateDate:
          type: string
          format: date-time
          description: Timestamp of when this update was recorded.
          example: "2020-09-10T10:51:23-07:00"
        Uri:
          type: string
          description: Unique URI reference to this action update object.
          example: "/Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/ActionUpdates/1000.4636.158133.95095059"

    QueuedResponse:
      type: object
      description: Returned when a modification or reversal request has been accepted and queued for processing.
      properties:
        Status:
          type: string
          description: Indicates the status of the request. A successful submission returns `QUEUED`.
          example: "QUEUED"
        QueuedUri:
          type: string
          description: The URI of the API submission record, which can be used to track the status of the queued request.
          example: "/Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/APISubmissions/A-4632dba3-2211-4615-a62d-6e121ddcdfa1"
