openapi: 3.2.0
info:
  title: Brand API - Actions Action Updates API
  description: 'API for managing conversion events (Actions), their associated line items, and their modification history (ActionUpdates).


    - **Actions**: Represents conversion events credited to partners. Use this to retrieve, update, or reverse actions and their items.

    - **ActionUpdates**: Functions as a changelog, providing a feed of all modifications made to actions.'
  version: v14
servers:
- url: https://api.impact.com
security:
- basicAuth: []
tags:
- name: Action Updates
paths:
  /Advertisers/{AccountSID}/ActionUpdates:
    get:
      summary: List action updates
      description: 'Returns a list of action updates, which serve as a changelog for actions.

        It is recommended to filter by a date range using `StartDate` and `EndDate`.


        **Date filtering constraints (effective 5 August 2024):**

        - `StartDate` cannot be more than 3 years in the past.

        - The range between `StartDate` and `EndDate` cannot exceed 45 days.

        - If neither is specified, only the past 7 days are returned.

        - If `StartDate` is specified, `EndDate` must also be specified.


        **Recommendation:** Use action lifecycle postbacks instead of this endpoint for near-realtime updates.

        '
      operationId: listActionUpdates
      tags:
      - Action Updates
      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 view 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 with EndDate.
        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 with StartDate.
        schema:
          type: string
          format: date-time
        example: '2024-01-31T23:59:59Z'
      - name: State
        in: query
        description: Filters updates to only those that match the State value passed.
        schema:
          type: string
          enum:
          - PENDING
          - APPROVED
          - REVERSED
        example: PENDING
      - name: ActionDateStart
        in: query
        description: Filters for updates with an ActionDate (EventDate) on or after this value (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: ActionDateEnd
        in: query
        description: Filters for updates with an ActionDate (EventDate) on or before this value (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2024-01-31T23:59:59Z'
      - name: LockingDateStart
        in: query
        description: Filters for updates with a LockingDate on or after this value (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: LockingDateEnd
        in: query
        description: Filters for updates with a LockingDate on or before this value (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2024-01-31T23:59:59Z'
      responses:
        '200':
          description: A paginated list of action update objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ActionUpdates:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActionUpdate'
      x-codeSamples:
      - lang: cURL
        source: "curl 'https://api.impact.com/Advertisers/<AccountSID>/ActionUpdates?CampaignId=1000&StartDate=2024-01-01T00:00:00Z&EndDate=2024-01-31T23:59:59Z' \\\n  -X GET \\\n  -u '<AccountSID>:<AuthToken>' \\\n  -H 'Accept: application/json'"
  /Advertisers/{AccountSID}/ActionUpdates/{ActionUpdateId}:
    get:
      summary: Get action update details
      description: Retrieves the details for a specific update to an action by its unique ActionUpdateId.
      operationId: getActionUpdateById
      tags:
      - Action Updates
      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: An action update object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionUpdate'
      x-codeSamples:
      - lang: cURL
        source: "curl 'https://api.impact.com/Advertisers/<AccountSID>/ActionUpdates/1000.4636.158133.95095059' \\\n  -X GET \\\n  -u '<AccountSID>:<AuthToken>' \\\n  -H 'Accept: application/json'"
components:
  schemas:
    ActionUpdate:
      type: object
      description: Represents a single modification event in an action's lifecycle. Each time an action changes state or is modified, a new ActionUpdate record is created.
      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
        CampaignId:
          type: integer
          description: Unique identifier for the campaign this action belongs to.
          example: 1000
        ActionTrackerId:
          type: integer
          description: Unique identifier for the action tracker (event type).
          example: 2240
        EventTypeId:
          type: string
          description: Alias for ActionTrackerId. The unique identifier of the event type.
          example: '2240'
        EventTypeName:
          type: string
          description: Display name of the event type (action tracker).
          example: Sale
        EventCode:
          type: string
          description: The event code associated with the action tracker, if configured.
          example: ''
        MediaPartnerId:
          type: integer
          description: Unique identifier for the partner credited for this action.
          example: 10000
        State:
          type: string
          description: The state of the action at the time of this update.
          enum:
          - PENDING
          - APPROVED
          - REVERSED
          example: PENDING
        StateDetail:
          type: string
          description: A short code providing additional detail about the action's state (e.g., `PAID`, `OVERDUE`).
          example: ''
        StateDetailDescription:
          type: string
          description: A plain-text description of the StateDetail code.
          example: Action comes in DEFAULT and a locking date has not been set yet
        AdId:
          type: integer
          description: Unique identifier for the ad creative that drove the winning click.
          example: 506720
        Disposition:
          type: string
          description: The disposition code applied to this update (e.g., `IR_BLANK`, `ORDER_UPDATE`).
          example: IR_BLANK
        DeltaPayout:
          type: number
          description: The change in payout value recorded by this update.
          example: 0.65
        DeltaAmount:
          type: number
          description: The change in sale amount recorded by this update.
          example: 16.29
        Currency:
          type: string
          description: Three-letter ISO 4217 currency code for monetary values in this update.
          example: USD
        Category:
          type: string
          description: Product category of the item associated with this update.
          example: Sports
        Sku:
          type: string
          description: SKU of the item associated with this update.
          example: '12345'
        Quantity:
          type: string
          description: Quantity of the item at the time of this update.
          example: '2'
        CatalogName:
          type: string
          description: Name of the product catalog entry associated with the item, if applicable.
          example: ''
        CatalogCategory:
          type: string
          description: Category from the product catalog entry, if applicable.
          example: ''
        CatalogDescription:
          type: string
          description: Description from the product catalog entry, if applicable.
          example: ''
        CatalogManufacturer:
          type: string
          description: Manufacturer from the product catalog entry, if applicable.
          example: ''
        CatalogOriginalFormatCategory:
          type: string
          description: Original format category from the product catalog entry, if applicable.
          example: ''
        CatalogSubCategory:
          type: string
          description: Sub-category from the product catalog entry, if applicable.
          example: ''
        PayoutLevel:
          type: string
          description: Indicates whether the payout is calculated at the order level or item level (e.g., `ORDER`, `ITEM`).
          example: ITEM
        DefaultPayoutRate:
          type: string
          description: The default payout rate defined in the event type settings.
          example: '2'
        ContractId:
          type: string
          description: The unique identifier for the contract (partnership agreement) associated with this action.
          example: S-3240326
        UpdateDate:
          type: string
          format: date-time
          description: Timestamp of when this update was recorded.
          example: '2020-09-10T10:51:23-07:00'
        LockingDate:
          type: string
          format: date-time
          description: Date after which the action can no longer be modified.
          example: '2020-09-26T00:00:00-07:00'
        ClearingDate:
          type: string
          format: date-time
          nullable: true
          description: Date when the commission is scheduled to clear.
          example: '2020-09-30T00:00:00-07:00'
        ActionDate:
          type: string
          format: date-time
          description: Timestamp of the original conversion event.
          example: '2020-09-10T10:42:38-07:00'
        Oid:
          type: string
          description: Your unique identifier for the order associated with the parent action.
          example: '9217374917472'
        CustomerId:
          type: string
          description: Your unique, non-PII identifier for the customer.
          example: BCZ2WVSH674563PDPYOTM3AXDQ
        CustomerStatus:
          type: string
          description: The customer status label at the time of this update.
          example: ''
        SharedId:
          type: string
          description: The Shared ID value from the winning click.
          example: RT-19247423
        ActionUri:
          type: string
          format: uri-reference
          description: URI reference to the parent action object.
          example: /Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/Actions/1000.4636.158133
        Uri:
          type: string
          format: uri-reference
          description: Unique URI reference to this action update object.
          example: /Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/ActionUpdates/1000.4636.158133.95095059
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
x-default-client: cURL