[Draft] 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:

1. In the left navigation menu, select [Engage] → Program Rules.
2. Select Add Rule within the Program rules section.

3. Select Friend refunds a purchase as the rule trigger from the dropdown menu.
4. Select the purchase event that the refund is associated to, and give the rule a name.
5. Select Next.
6. Select the action you want to take once it triggers.
7. Give the action a name, then select Next.
8. 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.

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"
}

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

1. In the top navigation bar, select [User Profile] → Settings.
2. Under the technical section, select File Submissions to see if the file has been processed.
   1. 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:

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