Process Order Refunds and Retractions in Advocate

This guide explains how to process order refunds and retractions as well as reward cancellations within the Advocate program.

Step 1: Set up your Advocate program rule configuration

To enable automatic reward retraction when a referred purchase is refunded, you must configure a specific rule in your Advocate program. This rule is essential. Without it, API calls to reverse actions will not trigger reward retraction.

In the impact.com platform:

In the left navigation menu, select [Engage] → Program Rules.
Select Add Rule within the Program rules section.
Select Friend refunds a purchase as the rule trigger from the dropdown menu.
Select the purchase event that the refund is associated to, and give the rule a name.
Select Next.
Select the action you want to take once it triggers.
Give the action a name, then select Next.
Review the rule details, then select Save.

Step 2: Trigger a retraction action via API

Advocate requires a specific API call to process a refund or retraction. Do not create a new conversion event. Instead, use the Reverse an Action API to trigger the retraction.

Key requirements

You must include Amount = 0 in your API call to indicate a full retraction.

When you send a modification or reversal request, you can use two methods:

Use an order ID (OID) + event type ID (ActionTrackerID) combination: All actions associated with this event type ID and order ID will be reversed or modified.
Use an Action ID (action_id). Only the unique action will be reversed or modified.

How to find the ActionId:

Use the Get Rewards endpoint to list rewards.
Note: The API may require iterating over participants to find the correct reward/action. There is currently no direct way to search by Order ID.
Once you have the reward, extract the associated ActionId for use in the reverse action API call.

Example using Action ID:

cURL
curl 'https://api.impact.com/Advertisers/<AccountSID>/Actions' \
  -X DELETE \
  -u '<AccountSID>:<AuthToken>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'ActionId=1234.5678.9123456' \
  -d 'Amount=0'
  -d 'DispositionCode=RETRACTION'

Example using Order ID:

cURL
curl 'https://api.impact.com/Advertisers/<AccountSID>/Actions' \
  -X DELETE \
  -u '<AccountSID>:<AuthToken>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'ActionTrackerId=12345' \
  -d 'OrderId=abc_123' \
  -d 'Amount=0'
  -d 'DispositionCode=RETRACTION'

Example response

{
  "Status": "QUEUED",
  "QueuedUri": "/Advertisers/<AccountSID>/APISubmissions/A-f1534308-e731-4146-86b9-56992f50eefe"
}

Important: Setting Amount = 0 is required. This ensures the action is fully retracted and the reward is cancelled, not just treated as an adjustment.

Common pitfalls & troubleshooting

The Advocate program evaluates the event amount based on item-level fields (ItemPrice, ItemQuantity, etc.).

OrderDiscount and OrderSubTotalPostDiscount are recorded but do not drive the retraction logic. For a full refund, ensure that all item prices are set to 0 in the event payload.

For partial refunds, you’ll need to update the item prices to reflect the new (post-refund) amount.

If the retraction rule doesn’t trigger, double-check that:

The program rule is configured as described above.
The API call includes Amount = 0.
The correct ActionId is used.

Step 3: Submit batch reversals

Prepare your data file

Prepare a .CSV file containing your reversals. Use the following template:

ActionTrackerId,OrderId,Amount,Reason

Start by adding your action data in the first row under the headers. Then, save the file with an identifiable name, such as:

Batch_Mods_Reversals_2020_02_12.csv

Example file

ActionTrackerID,OrderId,Amount,Reason 
16027,O7427540,0,ITEM_RETURNED
16027,O8306075,0,OTHER

Refer to Batch Modifications and Reversals File Parameters and Reason Codes for a list of reason codes and fields that can be used in an FTP/SMTP batch modification or reversal.

Submit the file

Refer to Set Up & Submit Batch Modifications & Reversals via FTP or Email for instructions on how to submit the file.

Step 4: Review the results

In the top navigation bar, select [User Profile] → Settings.
Under the technical section, select File Submissions to see if the file has been processed. Submitted files will appear within 10-15 minutes of being processed.

You will see an ACTION_NOT_FOUND error on all lines that are related to Advocate events, this is normal and expected.

Confirm referrals were successfully retracted:

In the left navigation menu, select [Engage] → Reporting → Referral Feed.
Check if the referrals have been retracted. Retracted referrals will be listed with a status of Started and the date the Conversion was retracted.