Ctrlk
Help CenterContact Support

Actions

List actions

get

Returns a list of actions your campaign has recorded, filtered by the provided parameters. Actions are returned by creation date, with the most recently created actions appearing first.

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.

  • Default page size is 20,000 records. Minimum page size is 2,000.

  • If the total record count exceeds 10× the page size, an error is returned — reduce the date range or increase PageSize.

Note on StartDate/EndDate: These filter on the last updated date, not the event date. State transitions (e.g., Pending → Approved) are not considered updates and will not be reflected by these filters. Use LockingDateStart/LockingDateEnd to filter by approval date.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

Example: IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1
Query parameters
CampaignIdintegerRequired

The ID of the campaign (program) to list actions for.

Example: 1000
Statestring · enumOptional

Filters actions based on their current state.

Example: PENDINGPossible values:
StartDatestring · date-timeOptional

Filters for actions with a last updated date on or after this value (ISO 8601 with time component). Must be used with EndDate.

Example: 2024-01-01T00:00:00Z
EndDatestring · date-timeOptional

Filters for actions with a last updated date on or before this value (ISO 8601 with time component). Requires StartDate.

Example: 2024-01-31T23:59:59Z
ActionDateStartstring · date-timeOptional

Filters for actions with an EventDate on or after this value (ISO 8601 with time component). Can be used as an alternative to StartDate.

Example: 2024-01-01T00:00:00Z
ActionDateEndstring · date-timeOptional

Filters for actions with an EventDate on or before this value (ISO 8601 with time component). Requires ActionDateStart.

Example: 2024-01-31T23:59:59Z
LockingDateStartstring · date-timeOptional

Filters for actions with a LockingDate on or after this value (ISO 8601 with time component).

Example: 2024-01-01T00:00:00Z
LockingDateEndstring · date-timeOptional

Filters for actions with a LockingDate on or before this value (ISO 8601 with time component). Requires LockingDateStart.

Example: 2024-01-31T23:59:59Z
Responses
200

A paginated list of action objects.

application/json
get
/Advertisers/{AccountSID}/Actions
cURL
200

A paginated list of action objects.

Update an action or its items

put

Updates the specified action or its line items by setting the values of the parameters passed.

  • To update an action's top-level details (e.g., CustomerStatus), provide the ActionId (or ActionTrackerId and OrderId) and the fields to update.

  • To update one or more items within an action, provide the ActionId, Sku, and item-specific fields like Quantity and Amount.

Note: impact.com allows a maximum of 1,000 modifications per action.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

Body

Request body for updating an action or its line items. At least one identifier path must be provided: either ActionId and Reason, or ActionTrackerId + OrderId and Reason.

ActionIdstringOptional

The unique impact.com identifier for the action to update. Required unless ActionTrackerId and OrderId are used together.

Example: 1000.4636.158133
ActionTrackerIdintegerOptional

The event type ID. Required with OrderId if ActionId is not used.

Example: 2240
OrderIdstringOptional

Your unique order identifier. Required with ActionTrackerId if ActionId is not used.

Example: 9217374917472
ReasonstringOptional

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
DispositionCodestringOptional

Submit ORDER_UPDATE as the default value for updating an action. Custom disposition codes may be used if configured in event type settings.

Example: ORDER_UPDATE
AmountnumberOptional

The new total sale amount for the order. Setting to 0 on a tracked action with a non-zero amount will reverse the action.

Example: 19.99
CustomerStatusstringOptional

A new custom status for the customer (e.g., NEW, EXISTING). Must be configured in event type settings.

Example: EXISTING
SkustringOptional

SKU of the item to update. For bulk item updates use indexed params (Sku, Sku2, Sku3, etc.).

Example: 12345
Categorystring · max: 255Optional

Category for the product. Can be automatically pulled if a product catalog has been uploaded. For item-level modifications, include for each item.

Example: Footwear
QuantityintegerOptional

The new absolute quantity of the item. For bulk item updates use indexed params (Quantity, Quantity2, etc.).

Example: 2
ItemSubTotalDeltanumberOptional

A relative delta amount to add or subtract from the item's SaleAmount. Use instead of Amount for partial adjustments.

Example: -5
Responses
200

The update request has been queued.

application/json

Returned when a modification or reversal request has been accepted and queued for processing.

StatusstringOptional

Indicates the status of the request. A successful submission returns QUEUED.

Example: QUEUED
QueuedUristring · uri-referenceOptional

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
put
/Advertisers/{AccountSID}/Actions
cURL
200

The update request has been queued.

Reverse an action

delete

Reverses an action using its ActionId or a combination of ActionTrackerId and OrderId. This will cancel any pending payouts to partners for the action.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

Body

Request body for reversing an action.

ActionIdstringOptional

The unique impact.com identifier for the action to reverse. Required unless ActionTrackerId and OrderId are used together.

Example: 1000.4636.158133
ActionTrackerIdintegerOptional

The event type ID. Required with OrderId if ActionId is not used.

Example: 2240
OrderIdstringOptional

Your unique order identifier. Required with ActionTrackerId if ActionId is not used.

Example: 9217374917472
DispositionCodestring · enumRequired

Required. A valid code explaining the reason for the reversal. Changes the action status to REVERSED.

Example: ITEM_RETURNEDPossible values:
Responses
200

The reversal request has been queued.

application/json

Returned when a modification or reversal request has been accepted and queued for processing.

StatusstringOptional

Indicates the status of the request. A successful submission returns QUEUED.

Example: QUEUED
QueuedUristring · uri-referenceOptional

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
delete
/Advertisers/{AccountSID}/Actions
cURL
200

The reversal request has been queued.

Get action details

get

Retrieves the details of an existing action by its unique impact.com ActionId.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

ActionIdstringRequired

The unique impact.com identifier for the action.

Example: 1000.4636.158133
Responses
200

An action object.

application/json

Represents a conversion event credited to a partner.

IdstringOptional

Unique impact.com identifier for the action.

Example: 1000.4636.158133
CampaignIdintegerOptional

Unique identifier for the campaign (program) this action belongs to.

Example: 1000
CampaignNamestringOptional

Display name of the campaign.

Example: Acme Campaign
ActionTrackerIdintegerOptional

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

Example: 2240
ActionTrackerNamestringOptional

Display name of the action tracker (event type).

Example: Sale
EventCodestringOptional

The event code associated with the action tracker, if configured.

MediaPartnerIdintegerOptional

Unique identifier for the partner credited for this action.

Example: 10000
MediaPartnerNamestringOptional

Display name of the credited partner.

Example: Acme Partner
Statestring · enumOptional

Current state of the action.

  • PENDING: Awaiting locking date or manual approval. Modified actions also carry this state.
  • APPROVED: Reached its locking date or was manually approved. Will pay out the partner.
  • REVERSED: Was reversed and will not pay out the partner.
Example: PENDINGPossible values:
AdIdintegerOptional

Unique identifier for the ad creative that drove the winning click.

Example: 506720
ClientCostnumberOptional

The total cost to the brand for this action (payout plus any fees).

Example: 0.88
PayoutnumberOptional

Commission amount to be paid to the partner.

Example: 0.88
DeltaPayoutnumberOptional

The change in payout value from the most recent modification. Equals Payout for unmodified actions.

Example: 0.88
IntendedPayoutnumberOptional

The originally intended payout before any modifications.

Example: 0.88
AmountnumberOptional

Revenue amount (sale amount) associated with this action.

Example: 21.99
DeltaAmountnumberOptional

The change in sale amount from the most recent modification. Equals Amount for unmodified actions.

Example: 21.99
IntendedAmountnumberOptional

The originally intended sale amount before any modifications.

Example: 21.99
CurrencystringOptional

Three-letter ISO 4217 currency code for monetary values in this action.

Example: USD
ReferringDatestring · date-timeOptional

Timestamp of the winning click that led to this conversion.

Example: 2020-09-10T09:45:07-07:00
EventDatestring · date-timeOptional

Timestamp of when the conversion event occurred.

Example: 2020-09-10T10:42:38-07:00
CreationDatestring · date-timeOptional

Timestamp of when this action record was created in impact.com.

Example: 2020-09-10T10:51:23-07:00
LockingDatestring · date-timeOptional

Date after which the action can no longer be modified. Once passed, a Pending action moves to Approved.

Example: 2020-09-26T00:00:00-07:00
ClearedDatestring · date-time · nullableOptional

Date when the commission for this action was cleared and paid out. Empty if not yet cleared.

ReferringTypestringOptional

The type of referral that drove the winning click (e.g., CLICK_COOKIE, CLICK_FINGERPRINT).

Example: CLICK_COOKIE
ReferringDomainstringOptional

Domain of the website where the winning click occurred. May be empty.

PromoCodestringOptional

Promotional code applied during the conversion, if any.

Example: SUMMERSALE2020
OidstringOptional

Your unique identifier for the order associated with this action.

Example: 9217374917472
CustomerIdstringOptional

Your unique, non-PII identifier for the customer who made the conversion.

Example: BCZ2WVSH674563PDPYOTM3AXDQ
CustomerStatusstringOptional

A custom status label for the customer, as defined in your event type settings (e.g., NEW, EXISTING).

Example: NEW
CustomerPostCodestringOptional

Postal code of the customer, if passed at conversion time.

Example: 15122
CustomerAreastringOptional

Area or neighbourhood of the customer, if passed at conversion time.

Example: n/a
CustomerCitystringOptional

City of the customer, if passed at conversion time.

Example: Santa Barbara
CustomerRegionstringOptional

State or region of the customer, if passed at conversion time.

Example: California
CustomerCountrystringOptional

Two-letter ISO country code for the customer's country, if passed at conversion time.

Example: US
IpAddressstringOptional

Hashed IP address of the customer at the time of conversion.

Example: 979823c536b3e06e4f1ee31af1f82b9d
SharedIdstringOptional

The Shared ID value passed from the winning click, used for cross-device or cross-channel attribution.

Example: RT-19247423
CallerIdstringOptional

Caller ID associated with the action, used in call tracking integrations.

NotestringOptional

Free-text note attached to the action, if any.

Uristring · uri-referenceOptional

Unique URI reference to this action object.

Example: /Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/Actions/1000.4636.158133
get
/Advertisers/{AccountSID}/Actions/{ActionId}
cURL
200

An action object.

List action items

get

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.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

ActionIdstringRequired

The unique impact.com identifier for the action.

Example: 1000.4636.158133
Responses
200

A paginated list of action item objects.

application/json
get
/Advertisers/{AccountSID}/Actions/{ActionId}/Items
cURL
200

A paginated list of action item objects.

Get action item details

get

Retrieves the details of a specific line item within an action. Requires the ActionId and the item's Sku.

Authorizations
AuthorizationstringRequired

Use your AccountSID as the username and AuthToken as the password.

Path parameters
AccountSIDstringRequired

Your unique account identifier.

ActionIdstringRequired

The unique impact.com identifier for the action.

Example: 1000.4636.158133
SkustringRequired

The Stock-Keeping Unit (SKU) or product identifier of the item.

Example: 12345
Responses
200

An action item object.

application/json

Represents a single line item within an action.

SkustringOptional

Stock-keeping unit (SKU) or product identifier for the item.

Example: 12345
ItemNamestringOptional

Display name of the product.

Example: Acme Tennis Balls (One Dozen)
CategorystringOptional

Product category for the item.

Example: Sports
QuantitystringOptional

Number of units of this product in the order.

Example: 2
SaleAmountstringOptional

Revenue amount for this line item.

Example: 19.27
SaleAmountCurrencystringOptional

Three-letter ISO 4217 currency code for the sale amount.

Example: USD
PayoutnumberOptional

Commission amount for this line item.

Example: 0.77
PayoutCurrencystringOptional

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

Example: USD
RebatenumberOptional

Discount or rebate amount applied to this item.

Example: 1
RebateCurrencystringOptional

Three-letter ISO 4217 currency code for the rebate amount.

Example: USD
AdjustmentDatestring · date-time · nullableOptional

Timestamp of the most recent adjustment to this item. Empty if the item has not been modified.

AdjustmentReasonstringOptional

The reason code for the most recent adjustment to this item.

Uristring · uri-referenceOptional

Unique URI reference to this action item object.

Example: /Advertisers/IRyMQiCNtwrt1804207G3t8Pn6NyzfyDw1/Actions/1000.4636.158133/Items/12345
get
/Advertisers/{AccountSID}/Actions/{ActionId}/Items/{Sku}
cURL
200

An action item object.

PreviousActionsNextAction Updates

Last updated