Actions

Endpoints for managing and tracking conversion events and updates.

List Actions

get

Returns a list of actions attributed to you, ordered by creation date (newest first).

Date filtering rules:

If no StartDate and EndDate are specified, only records from the past 7 days are returned.
StartDate and EndDate cannot be more than 45 days apart.
StartDate cannot exceed 3 years in the past.
If StartDate is specified, EndDate must also be specified.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

Query parameters

CampaignIdintegerOptional

Filters actions for a specific campaign.

Statestring · enumOptional

The current state of the action.

Possible values:

ActionDateStartstring · date-timeOptional

Filters actions with an EventDate on or after this value.

ActionDateEndstring · date-timeOptional

Filters actions with an EventDate on or before this value.

StartDatestring · date-timeOptional

Filters actions last updated on or after this value. Requires EndDate. Cannot be more than 45 days before EndDate or more than 3 years in the past.

EndDatestring · date-timeOptional

Filters actions last updated on or before this value. Requires StartDate.

LockingDateStartstring · date-timeOptional

Filters actions with a LockingDate on or after this value. Requires LockingDateEnd. The range between LockingDateStart and LockingDateEnd cannot exceed 45 days.

LockingDateEndstring · date-timeOptional

Filters actions with a LockingDate on or before this value. Requires LockingDateStart.

Responses

200

A list of action objects.

application/json

get/Mediapartners/{AccountSID}/Actions

GET /Mediapartners/{AccountSID}/Actions HTTP/1.1
Host: api.impact.com
Accept: */*

200

A list of action objects.

{
  "Actions": [
    {
      "Id": "1000.4636.158133",
      "CampaignId": "1000",
      "CampaignName": "Acme Campaign",
      "ActionTrackerId": "2240",
      "ActionTrackerName": "Sale",
      "State": "PENDING",
      "AdId": "506720",
      "Payout": "0.88",
      "Amount": "21.99",
      "Currency": "USD",
      "EventDate": "2024-09-10T10:42:38-07:00",
      "LockingDate": "2024-09-26T00:00:00-07:00",
      "Oid": "9217374917472",
      "EventCode": "",
      "SharedId": "RT-19247423",
      "SubId1": "",
      "SubId2": "",
      "SubId3": "",
      "DeltaPayout": "0.88",
      "IntendedPayout": "0.88",
      "DeltaAmount": "21.99",
      "IntendedAmount": "21.99",
      "ReferringDate": "2024-09-10T09:45:07-07:00",
      "CreationDate": "2024-09-10T10:51:23-07:00",
      "ClearedDate": "",
      "ReferringType": "CLICK_COOKIE",
      "ReferringDomain": "",
      "PromoCode": "SUMMERSALE2024",
      "CustomerArea": "855",
      "CustomerCity": "Santa Barbara",
      "CustomerRegion": "California",
      "CustomerCountry": "US",
      "Uri": "/Mediapartners/<AccountSID>/Actions/1000.4636.158133"
    }
  ]
}

Retrieve an Action

get

Retrieves the details of an existing action using its unique ID.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

idstringRequired

Unique identifier for the action.

Responses

200

The action object.

application/json

IdstringOptional

Unique identifier for the action.

Example: 1000.4636.158133

CampaignIdintegerOptional

Unique identifier for the campaign that the action is associated with.

Example: 1000

CampaignNamestringOptional

Display name for the campaign that the action is associated with.

Example: Acme Campaign

ActionTrackerIdintegerOptional

Unique identifier for the action tracker (event type) that tracked the conversion.

Example: 2240

ActionTrackerNamestringOptional

Display name for the action tracker (event type) that tracked the conversion.

Example: Sale

Statestring · enumOptional

The current state of the action:

PENDING: Awaiting the locking date for automatic approval, or manual review. Modified actions also have this state.
APPROVED: Approved and will pay out to the partner. No further modifications are possible.
REVERSED: Reversed and will not pay out to the partner.

Possible values:

AdIdintegerOptional

Unique identifier for the ad that drove the winning click.

Example: 506720

Payoutstring · decimalOptional

Commission amount calculated for the action that will be paid out to the partner.

Example: 0.88

Amountstring · decimalOptional

Revenue amount associated with the action.

Example: 21.99

CurrencystringOptional

Three-letter ISO 4217 code representing the currency for the action.

Example: USD

EventDatestring · date-timeOptional

Date and time when the conversion event occurred.

Example: 2024-09-10T10:42:38-07:00

LockingDatestring · date-timeOptional

Date and time when the action will lock and can no longer be modified or reversed.

Example: 2024-09-26T00:00:00-07:00

OidstringOptional

The unique identifier for the order associated with this conversion, as provided by the brand.

Example: 9217374917472

EventCodestringOptional

For mobile app events, populates with the event code representing the type of event tracked.

SharedIdstringOptional

The Shared ID value associated with the winning click. A query string parameter you can append to the tracking link to share traffic segments with the brand.

Example: RT-19247423

SubId1stringOptional

The first Sub ID value associated with the winning click. A query string parameter you can append to the tracking link that will appear in your reporting.

SubId2stringOptional

The second Sub ID value associated with the winning click. A query string parameter you can append to the tracking link that will appear in your reporting.

SubId3stringOptional

The third Sub ID value associated with the winning click. A query string parameter you can append to the tracking link that will appear in your reporting.

DeltaPayoutstring · decimalOptional

The change in payout value between the current action update and the previous one.

Example: 0.88

IntendedPayoutstring · decimalOptional

Original payout amount calculated by the template terms before any modifications.

Example: 0.88

DeltaAmountstring · decimalOptional

The change in amount value between the current action update and the previous one.

Example: 21.99

IntendedAmountstring · decimalOptional

Original amount for the action before any modifications.

Example: 21.99

ReferringDatestring · date-timeOptional

Date and time when the winning click occurred.

Example: 2024-09-10T09:45:07-07:00

CreationDatestring · date-timeOptional

Date and time when the action was created in impact.com.

Example: 2024-09-10T10:51:23-07:00

ClearedDatestring · date-timeOptional

Date and time when the action commission cleared your account balance. Returns empty if the action has not cleared yet.

ReferringTypestring · enumOptional

The attribution method associated with the winning referral.

Example: CLICK_COOKIEPossible values:

ReferringDomainstringOptional

Domain of the site that the winning click occurred on.

PromoCodestringOptional

The promotional code applied to the conversion, if one was used.

Example: SUMMERSALE2024

CustomerAreastringOptional

The Designated Market Area (DMA) code of the customer's area, derived from IP address.

Example: 855

CustomerCitystringOptional

The city the customer resides in.

Example: Santa Barbara

CustomerRegionstringOptional

The region or state the customer resides in.

Example: California

CustomerCountrystringOptional

The country the customer resides in.

Example: US

UristringOptional

Unique reference to the action object in the impact.com API.

Example: /Mediapartners/<AccountSID>/Actions/1000.4636.158133

get/Mediapartners/{AccountSID}/Actions/{id}

GET /Mediapartners/{AccountSID}/Actions/{id} HTTP/1.1
Host: api.impact.com
Accept: */*

200

The action object.

{
  "Id": "1000.4636.158133",
  "CampaignId": "1000",
  "CampaignName": "Acme Campaign",
  "ActionTrackerId": "2240",
  "ActionTrackerName": "Sale",
  "State": "PENDING",
  "AdId": "506720",
  "Payout": "0.88",
  "Amount": "21.99",
  "Currency": "USD",
  "EventDate": "2024-09-10T10:42:38-07:00",
  "LockingDate": "2024-09-26T00:00:00-07:00",
  "Oid": "9217374917472",
  "EventCode": "",
  "SharedId": "RT-19247423",
  "SubId1": "",
  "SubId2": "",
  "SubId3": "",
  "DeltaPayout": "0.88",
  "IntendedPayout": "0.88",
  "DeltaAmount": "21.99",
  "IntendedAmount": "21.99",
  "ReferringDate": "2024-09-10T09:45:07-07:00",
  "CreationDate": "2024-09-10T10:51:23-07:00",
  "ClearedDate": "",
  "ReferringType": "CLICK_COOKIE",
  "ReferringDomain": "",
  "PromoCode": "SUMMERSALE2024",
  "CustomerArea": "855",
  "CustomerCity": "Santa Barbara",
  "CustomerRegion": "California",
  "CustomerCountry": "US",
  "Uri": "/Mediapartners/<AccountSID>/Actions/1000.4636.158133"
}

List all items for an action

get

Returns a list of the items within the specified action in the order they were recorded. Each action has at least one item.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

idstringRequired

Unique identifier for the action.

Responses

200

An array of action item objects.

application/json

get/Mediapartners/{AccountSID}/Actions/{id}/Items

GET /Mediapartners/{AccountSID}/Actions/{id}/Items HTTP/1.1
Host: api.impact.com
Accept: */*

200

An array of action item objects.

{
  "ActionItems": [
    {
      "Sku": "12345",
      "ItemName": "Acme Tennis Balls (One Dozen)",
      "Category": "Sports",
      "Quantity": "2",
      "SaleAmount": "19.27",
      "SaleAmountCurrency": "USD",
      "Payout": "0.77",
      "PayoutCurrency": "USD",
      "Rebate": "1.00",
      "RebateCurrency": "USD",
      "AdjustmentDate": "",
      "AdjustmentReason": "",
      "Uri": "/Mediapartners/<AccountSID>/Actions/1000.4636.158133/Items/12345"
    }
  ]
}

Retrieve an item from an action

get

Retrieves the details of a specific item within an action using its SKU.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

actionIdstringRequired

Unique identifier for the action.

skustringRequired

The SKU or product identifier of the item.

Responses

200

A single action item object.

application/json

SkustringOptional

The product identifier or SKU for the item.

Example: 12345

ItemNamestringOptional

The product name or description.

Example: Acme Tennis Balls (One Dozen)

CategorystringOptional

The product category.

Example: Sports

QuantitystringOptional

The number of units purchased.

Example: 2

SaleAmountstringOptional

The transaction value or sale amount for the item.

Example: 19.27

SaleAmountCurrencystringOptional

The currency code for the sale amount.

Example: USD

Payoutstring · decimalOptional

The commission or payout earned for the item.

Example: 0.77

PayoutCurrencystringOptional

The currency code for the payout.

Example: USD

RebatestringOptional

The rebate amount for the item.

Example: 1.00

RebateCurrencystringOptional

The currency code for the rebate.

Example: USD

AdjustmentDatestring · date-timeOptional

The date and time of any adjustment applied to the item. Returns empty if no adjustment has occurred.

AdjustmentReasonstring · enumOptional

The reason for any adjustment applied to the item. Returns empty if no adjustment has occurred.

Possible values:

UristringOptional

Unique reference to the action item object in the impact.com API.

Example: /Mediapartners/<AccountSID>/Actions/1000.4636.158133/Items/12345

get/Mediapartners/{AccountSID}/Actions/{actionId}/Items/{sku}

GET /Mediapartners/{AccountSID}/Actions/{actionId}/Items/{sku} HTTP/1.1
Host: api.impact.com
Accept: */*

200

A single action item object.

{
  "Sku": "12345",
  "ItemName": "Acme Tennis Balls (One Dozen)",
  "Category": "Sports",
  "Quantity": "2",
  "SaleAmount": "19.27",
  "SaleAmountCurrency": "USD",
  "Payout": "0.77",
  "PayoutCurrency": "USD",
  "Rebate": "1.00",
  "RebateCurrency": "USD",
  "AdjustmentDate": "",
  "AdjustmentReason": "",
  "Uri": "/Mediapartners/<AccountSID>/Actions/1000.4636.158133/Items/12345"
}

List Action Updates

get

Returns a list of action updates, useful for syncing action state changes with internal systems. Each record represents a change to an action's state or payout.

Note: impact.com recommends using action lifecycle postbacks instead of polling this endpoint for all but occasional requests, in order to receive low-latency near-realtime action updates.

Date filtering rules:

If no StartDate and EndDate are specified, only records from the past 7 days are returned.
StartDate and EndDate cannot be more than 45 days apart.
StartDate cannot exceed 3 years in the past.
If StartDate is specified, EndDate must also be specified.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

Query parameters

StartDatestring · date-timeOptional

Filters action updates last modified on or after this value. Requires EndDate. Cannot be more than 45 days before EndDate or more than 3 years in the past.

EndDatestring · date-timeOptional

Filters action updates last modified on or before this value. Requires StartDate.

CampaignIdintegerOptional

Filters action updates for a specific campaign.

Statestring · enumOptional

The current state of the action.

Possible values:

ActionDateStartstring · date-timeOptional

Filters action updates whose action's EventDate is on or after this value. Requires ActionDateEnd. The range cannot exceed 45 days.

ActionDateEndstring · date-timeOptional

Filters action updates whose action's EventDate is on or before this value. Requires ActionDateStart.

LockingDateStartstring · date-timeOptional

Filters action updates whose action's LockingDate is on or after this value. Requires LockingDateEnd. The range cannot exceed 45 days.

LockingDateEndstring · date-timeOptional

Filters action updates whose action's LockingDate is on or before this value. Requires LockingDateStart.

Responses

200

An array of action update objects.

application/json

get/Mediapartners/{AccountSID}/ActionUpdates

GET /Mediapartners/{AccountSID}/ActionUpdates HTTP/1.1
Host: api.impact.com
Accept: */*

200

An array of action update objects.

{
  "ActionUpdates": [
    {
      "Id": "1000.1234.56789.10111213",
      "ActionId": "1000.1234.56789",
      "CampaignId": "1000",
      "ActionTrackerId": "10000",
      "EventCode": "",
      "State": "PENDING",
      "StateDetail": "",
      "StateDetailDescription": "Action comes in DEFAULT and a locking date has not been set yet",
      "AdId": "123456",
      "ReportingState": "IR_BLANK",
      "DeltaPayout": "0.26",
      "DeltaAmount": "17.29",
      "Currency": "USD",
      "Category": "Sports",
      "Sku": "123ABC456",
      "Quantity": "1",
      "CatalogName": "",
      "CatalogCategory": "",
      "CatalogDescription": "",
      "CatalogManufacturer": "",
      "CatalogOriginalFormatCategory": "",
      "CatalogSubCategory": "",
      "UpdateDate": "2021-04-25T02:07:45-04:00",
      "LockingDate": "2021-05-16T00:00:00-04:00",
      "ClearingDate": "2021-05-16T00:00:00-04:00",
      "ActionDate": "2021-04-24T19:50:23-04:00",
      "Oid": "O987654",
      "SubId1": "Blog",
      "SubId2": "Website",
      "SubId3": "",
      "PaystubId": "116142",
      "ContractId": "S-7751552",
      "EventTypeId": "10000",
      "EventTypeName": "Sale",
      "PayoutLevel": "ORDER",
      "DefaultPayout": "5.00",
      "DefaultPayoutCurrency": "USD",
      "SharedId": "",
      "ActionUri": "/Mediapartners/<AccountSID>/Actions/1000.1234.56789",
      "Uri": "/Mediapartners/<AccountSID>/ActionUpdates/1000.1234.56789.10111213"
    }
  ]
}

Retrieve an Action Update

get

Retrieves the details of a specific action update record.

Path parameters

AccountSIDstringRequired

Unique identifier for the partner account.

idstringRequired

Unique identifier for the action update record.

Responses

200

A single action update object.

application/json

IdstringOptional

Unique identifier for the action update record.

Example: 1000.1234.56789.10111213

ActionIdstringOptional

Identifier for the parent action associated with this update.

Example: 1000.1234.56789

CampaignIdintegerOptional

Unique identifier for the campaign associated with the action.

Example: 1000

ActionTrackerIdstringOptional

Unique identifier of the action tracker (event type) that recorded the action.

Example: 10000

EventCodestringOptional

Internal event code associated with the action tracker.

Statestring · enumOptional

The current state of the action:

PENDING: Awaiting the locking date for automatic approval, or manual review.
APPROVED: Approved and will pay out to the partner.
REVERSED: Reversed and will not pay out to the partner.

Possible values:

StateDetailstringOptional

Additional detail about the current state of the action.

StateDetailDescriptionstringOptional

Human-readable explanation of the state detail.

Example: Action comes in DEFAULT and a locking date has not been set yet

AdIdstringOptional

Unique identifier of the ad that drove the action, if applicable.

Example: 123456

ReportingStatestringOptional

The reporting state of the action used by impact.com analytics.

Example: IR_BLANK

DeltaPayoutstring · decimalOptional

The change in payout amount between this update and the previous one.

Example: 0.26

DeltaAmountstring · decimalOptional

The change in transaction amount between this update and the previous one.

Example: 17.29

CurrencystringOptional

Three-letter ISO 4217 currency code for the action amounts.

Example: USD

CategorystringOptional

Brand-defined category for the action.

Example: Sports

SkustringOptional

Stock keeping unit identifier for the product associated with the action, if applicable.

Example: 123ABC456

QuantitystringOptional

Quantity of items associated with the action.

Example: 1

CatalogNamestringOptional

Name of the catalog the action item belongs to.

CatalogCategorystringOptional

Category of the action item from the brand's catalog.

CatalogDescriptionstringOptional

Description of the action item from the brand's catalog.

CatalogManufacturerstringOptional

Manufacturer of the action item from the brand's catalog.

CatalogOriginalFormatCategorystringOptional

Original (unmodified) category of the action item from the brand's catalog.

CatalogSubCategorystringOptional

Sub-category of the action item from the brand's catalog.

UpdateDatestring · date-timeOptional

Date and time of the most recent modification to the action.

Example: 2021-04-25T02:07:45-04:00

LockingDatestring · date-timeOptional

Date and time the action will be (or was) locked for automatic state changes.

Example: 2021-05-16T00:00:00-04:00

ClearingDatestring · date-timeOptional

Date and time the action payout was (or will be) cleared for payment.

Example: 2021-05-16T00:00:00-04:00

ActionDatestring · date-timeOptional

Date and time when the original action or conversion event occurred.

Example: 2021-04-24T19:50:23-04:00

OidstringOptional

The unique identifier for the order associated with the action, as provided by the brand.

Example: O987654

SubId1stringOptional

First partner sub-identifier passed on the tracking link.

Example: Blog

SubId2stringOptional

Second partner sub-identifier passed on the tracking link.

Example: Website

SubId3stringOptional

Third partner sub-identifier passed on the tracking link.

PaystubIdstringOptional

Identifier of the paystub the action's payout is associated with, when paid.

Example: 116142

ContractIdstringOptional

Identifier of the contract that determined the payout for this action.

Example: S-7751552

EventTypeIdstringOptional

Unique identifier of the event type that recorded the action.

Example: 10000

EventTypeNamestringOptional

Display name of the event type that recorded the action.

Example: Sale

PayoutLevelstringOptional

The level at which the payout was calculated (e.g., ORDER, ITEM).

Example: ORDER

DefaultPayoutstring · decimalOptional

Default payout amount before any adjustments.

Example: 5.00

DefaultPayoutCurrencystringOptional

Three-letter ISO 4217 currency code for the default payout amount.

Example: USD

SharedIdstringOptional

Shared identifier passed on the tracking link.

ActionUristringOptional

API resource path to the parent action.

Example: /Mediapartners/<AccountSID>/Actions/1000.1234.56789

UristringOptional

Unique reference to the action update object in the impact.com API.

Example: /Mediapartners/<AccountSID>/ActionUpdates/1000.1234.56789.10111213

get/Mediapartners/{AccountSID}/ActionUpdates/{id}

GET /Mediapartners/{AccountSID}/ActionUpdates/{id} HTTP/1.1
Host: api.impact.com
Accept: */*

200

A single action update object.

{
  "Id": "1000.1234.56789.10111213",
  "ActionId": "1000.1234.56789",
  "CampaignId": "1000",
  "ActionTrackerId": "10000",
  "EventCode": "",
  "State": "PENDING",
  "StateDetail": "",
  "StateDetailDescription": "Action comes in DEFAULT and a locking date has not been set yet",
  "AdId": "123456",
  "ReportingState": "IR_BLANK",
  "DeltaPayout": "0.26",
  "DeltaAmount": "17.29",
  "Currency": "USD",
  "Category": "Sports",
  "Sku": "123ABC456",
  "Quantity": "1",
  "CatalogName": "",
  "CatalogCategory": "",
  "CatalogDescription": "",
  "CatalogManufacturer": "",
  "CatalogOriginalFormatCategory": "",
  "CatalogSubCategory": "",
  "UpdateDate": "2021-04-25T02:07:45-04:00",
  "LockingDate": "2021-05-16T00:00:00-04:00",
  "ClearingDate": "2021-05-16T00:00:00-04:00",
  "ActionDate": "2021-04-24T19:50:23-04:00",
  "Oid": "O987654",
  "SubId1": "Blog",
  "SubId2": "Website",
  "SubId3": "",
  "PaystubId": "116142",
  "ContractId": "S-7751552",
  "EventTypeId": "10000",
  "EventTypeName": "Sale",
  "PayoutLevel": "ORDER",
  "DefaultPayout": "5.00",
  "DefaultPayoutCurrency": "USD",
  "SharedId": "",
  "ActionUri": "/Mediapartners/<AccountSID>/Actions/1000.1234.56789",
  "Uri": "/Mediapartners/<AccountSID>/ActionUpdates/1000.1234.56789.10111213"
}

PreviousActions

NextModels

Last updated 2 months ago