View desktop instructions

View mobile app instructions
Set Up & Submit Batch Modifications & Reversals via FTP or Email

Published on: Mon, 17 Jul, 2023 at 1:52 AM | Updated on: Tue, 11 Mar, 2025 at 3:56 AM

You can use our .csv template files below to help guide you in preparing a file with your modifications and reversals. The template file you need depends on whether you're tracking at the order level or item level, as each requires different fields. If you're unsure about which file to use, ask your CSM or contact support.

Set up your data file

Copy the batch template file relevant to your use case. Refer to the file examples section below for more information.
Item-level templates
Item-level template (with ActionId):
ActionId,Sku,Amount,Quantity,Category,Reason
Item-level template (with ActionTrackerId and OrderId):
ActionTrackerId,OrderId,Sku,Amount,Quantity,Category,Reason
Amount is required for modifications. Set the Amount to 0 for reversals unless the original Amount = 0.
Category is required for modifications. Do not include this parameter for reversals.
Quantity is optional for modifications but required for reversals.
Order-level templates
Order-level template (with ActionId):
ActionId,Amount,Reason,CustomerStatus
Order-level template (with ActionTrackerId and OrderId):
ActionTrackerId,OrderId,Amount,Reason,CustomerStatus
CustomerStatus is optional for modifications. Do not include this parameter for reversals.
Paste the template file with a spreadsheet application (such as Microsoft Excel) or a text editor (such as Notepad or TextEdit).
In the second row (i.e., the first row under the headers), start adding your action data.
- If you are using a spreadsheet app, add each data point in a separate cell.
- If you are using a text editor, use commas to separate each data point.
Important: Make sure you're editing the cells in "Plain text" or "Text" format so that values aren't accidentally omitted.
Save the file with an identifiable name, such as:
Batch_Mods_Reversals_2020_02_12.csv
- impact.com also supports .xml files for batch modifications & reversals. See the File examples section below to see an example of .xml files formatted for batch modifications & reversals.
- Refer to Batch Modifications and Reversals File Parameters and Reason Codes to see which fields can be used in an FTP/SMTP batch modification or reversal.

Submit your data file

From the left navigation menu, select [Menu] → Settings.
On the right, under Tracking, select Event Types.
Select the name of the Event Type for which you want to submit batch modifications.
Next to Returns Processing, select [Edit].
Select Automate returns processing (advanced).

Choose your preferred upload method. If you don't see the following 3 options, visit impact.com 's integrations portal and submit your file via API instead.

Upload file to system FTP server

Select Upload file to system FTP server.
Select Email FTP Username and Password.
Once you have received your FTP credentials, use an FTP client to connect to impact.com with the following info:
Once connected, upload your file to the main directory of the server.
- If you have not received the FTP credentials email, contact the person who created your impact.com account. Alternatively, contact support.

Pull file from your own FTP server

Select Pull file from your own FTP server.
Enter the Server URL, Port, and directory path to the batch modifications file on your FTP server. Enter the Username and Password that impact.com will use to connect to your FTP server.
Select Save and continue.
Upload your batch modifications file to the directory you specified above.
- impact.com attempts to connect and download files from your FTP server every 24 hours. Wait at least 24 hours for impact.com to download your file.

Email file to system SMTP server

Select Email file to system SMTP server, then copy your unique email address.
Using any email client, send an email to the unique address with your batch modifications file as an attachment.
- Only include the unique email address for the event type in the To: field. If you need to send this file to others, include them in the CC: field.
You can leave the subject field and message body blank.

For this method, you'll need to have a connection set up. Once a connection is set up:

Select Batch upload.
Select your connection from the [Drop-down menu].
Select Save.

Note: impact.com allows a maximum of 1000 modifications per action. If you need to make further modifications thereafter, contact support.

Review the file submission

Once you've sent your batch .csv or .xml file to impact.com, you can check its current status and if it was processed.

From the left navigation menu, select [Menu] → Settings.
In the left column, scroll to the Technical section and select File Submissions.

Use the table to review recent file submissions that impact.com has received, including the current processing status.

Below you can view various errors you may encounter when reviewing file submissions and actions you can take to rectify them.

Errors when reviewing file submissions

Some common errors when reviewing file submission may include:

Issue	Action to take
Records column shows 0	Make sure the file extension is . CSV or .XML.
`NO_CHANGE`	There is no change made to the action. Please ensure you enter the final amount into the Amount column, (E.g. enter 0 if you want to reverse actions.).
`BAD_DISPOSITION`	The reason code is not valid. Please follow the standard reason codes. Alternatively, if you have custom disposition codes set up, proceed with the following: Navigate to [Menu] → Settings → Event Types. Select [More] and then select Disposition Codes. Important: If you want to approve actions, `Approve` needs to be set up as a custom disposition code.
`ALREADY_LOCKED`	The action has already been locked. No further changes can be made.
`ActionTrackerld:ActionTrackerld value is invalid`	This should correspond to the Event Type ID entered. Navigate to [Menu] → Settings → Event Types. Make sure to enter the correct Event Type ID.
`ACTION_NOT_FOUND`	The `OID` is incorrect. Please provide a correct `OID`.
`ALREADY_REVERSED`	The action has already been reversed.
`ALREADY_APPROVED`	The action has already been approved.

File examples

Expand the examples below to see what the body of a batch .csv or .xml file would look like, for batch reversals and modifications.

Order-level .csv

Reversals

ActionTrackerID,Oid,Amount,Reason 
16027,O7427540,0,ITEM_RETURNED
16027,O8306075,0, CONS_ERROR

Modifications

ActionTrackerID,Oid,Amount,Reason 
17651,O1234567,20,PUB_ACT_DISPUTE
16754,O6783215,10,ORDER_UPDATE

Approvals

ActionTrackerID,Oid,Amount,Reason 
17651,O1234567,20,APPROVED
16754,O6783215,10,APPROVED

Order-level .xml

Reversals

<?xml version="1.0" encoding="UTF-8"?>
<ActionReturnRequests xmlns="http://ws.impact.com/ws/definitions">
<ActionReturnRequest>
<ActionTrackerId>16027</ActionTrackerId>
<Oid>O7427540</Oid>
<Amount>0.00</Amount>
<Reason>ITEM_RETURNED</Reason>
</ActionReturnRequest>
<ActionReturnRequest>
<ActionTrackerId>16027</ActionTrackerId>
<Oid>O8306075</Oid>
<Amount>0.00</Amount>
<Reason>CONS_ERROR</Reason>
</ActionReturnRequest>
</ActionReturnRequests>

Modifications

<?xml version="1.0" encoding="UTF-8"?>
<ActionModifyRequests xmlns="http://ws.impact.com/ws/definitions">
<ActionModifyRequest>
<ActionTrackerId>17651</ActionTrackerId>
<Oid>O1234567</Oid>
<Amount>20.00</Amount>
<Reason>PUB_ACT_DISPUTE</Reason>
</ActionModifyRequest>
<ActionModifyRequest>
<ActionTrackerId>16754</ActionTrackerId>
<Oid>O6783215</Oid>
<Amount>10.00</Amount>
<Reason>ORDER_UPDATE</Reason>
</ActionModifyRequest>
</ActionModifyRequest>

Approvals

<?xml version="1.0" encoding="UTF-8"?>
<ActionModifyRequests xmlns="http://ws.impact.com/ws/definitions">
<ActionModifyRequest>
<ActionTrackerId>17651</ActionTrackerId>
<Oid>O1234567</Oid>
<Amount>20.00</Amount>
<Reason>APPROVED</Reason>
</ActionModifyRequest>
<ActionModifyRequest>
<ActionTrackerId>16754</ActionTrackerId>
<Oid>O6783215</Oid>
<Amount>10.00</Amount>
<Reason>APPROVED</Reason>
</ActionModifyRequest>
</ActionModifyRequest>

Item-level reversals and modifications

You always need the correct SKU and OID when doing item-level modifications and reversals.
Reversing items requires two additional values (SKU and Quantity) compared to an order reversal.
You can't modify a SKU (i.e., change an SKU) for item-level actions.
You can modify the quantity for item-level actions.

Item-level .csv

Reversals

ActionTrackerID,Oid,Amount,Sku,Quantity,Reason 
10307,O7427540,0,SKU123,0,ITEM_RETURNED 
10307,O7427540,15,SKU456,0,ORDER_ERROR 
10307,O8306075,0,SKU7890,0,ITEM_RETURNED

See above that the Order ID O7427540 is listed twice in line 1 and 2 — this is because there are two different SKUs in the order; one is being reversed (zeroed out) and one is being modified (changed to a new final value of 15).

Modifications

ActionTrackerID,Oid,Amount,Sku,Quantity,Reason 
17651,O1234567,20,SKU333,1,PUB_ACT_DISPUTE
16754,O6783215,10,SKU321,2,ORDER_UPDATE

Approvals

ActionTrackerID,Oid,Amount,Sku,Quantity,Reason 
17651,O1234567,20,SKU333,1,APPROVED
16754,O6783215,10,SKU321,2,APPROVED

Item-level .xml

Reversals

<?xml version="1.0" encoding="UTF-8"?>
<ItemActionReturnRequests xmlns="http://ws.impact.com/ws/definitions">
<ItemActionReturnRequest>
<ActionTrackerId>10307</ActionTrackerId>
<Oid>O7427540</Oid>
<Items>
<Item>
<Amount>0.00</Amount>
<Sku>SKU123</Sku>
<Quantity>0</Quantity>
<Reason>ITEM_RETURNED</Reason>
</Item>
<Item>
<Amount>15.00</Amount>
<Sku>SKU456</Sku>
<Quantity>1</Quantity>
<Reason>ORDER_ERROR</Reason>
</Item>
</Items>
</ItemActionReturnRequest>
<ItemActionReturnRequest>
<ActionTrackerId>10307</ActionTrackerId>
<Oid>O8306075</Oid>
<Items>
<Item>
<Amount>0.00</Amount>
<Sku>SKU789</Sku>
<Quantity>0</Quantity>
<Reason>ITEM_RETURNED</Reason>
</Item>
</Items>
</ItemActionReturnRequest>
</ItemActionReturnRequests>

Modifications

<?xml version="1.0" encoding="UTF-8"?>
<ItemActionModifyRequests xmlns="http://ws.impact.com/ws/definitions">
<ItemActionModifyRequest>
<ActionTrackerId>17651</ActionTrackerId>
<Oid>O1234567</Oid>
<Items>
<Item>
<Amount>20.00</Amount>
<Sku>SKU333</Sku>
<Quantity>1</Quantity>
<Reason>PUB_ACT_DISPUTE</Reason>
</Item>
<Items>
</ItemActionModifyRequest>
<Items>
<Item>
<Amount>10.00</Amount>
<Sku>SKU321</Sku>
<Quantity>1</Quantity>
<Reason>ORDER_UPDATE</Reason>
</Item>
<Item>
<Amount>10.00</Amount>
<Sku>SKU321</Sku>
<Quantity>1</Quantity>
<Reason>ORDER_UPDATE</Reason>
</Item>
</Items>
</ItemActionModifyRequest>
</ItemActionModifyRequest>

Approvals

<?xml version="1.0" encoding="UTF-8"?>
<ItemActionModifyRequests xmlns="http://ws.impact.com/ws/definitions">
<ItemActionModifyRequest>
<ActionTrackerId>17651</ActionTrackerId>
<Oid>O1234567</Oid>
<Items>
<Item>
<Amount>20.00</Amount>
<Sku>SKU333</Sku>
<Quantity>1</Quantity>
<Reason>APPROVED</Reason>
</Item>
<Items>
</ItemActionModifyRequest>
<Items>
<Item>
<Amount>10.00</Amount>
<Sku>SKU321</Sku>
<Quantity>1</Quantity>
<Reason>APPROVED</Reason>
</Item>
<Item>
<Amount>10.00</Amount>
<Sku>SKU321</Sku>
<Quantity>1</Quantity>
<Reason>APPROVED</Reason>
</Item>
</Items>
</ItemActionModifyRequest>
</ItemActionModifyRequest>

Set up your data file

Submit your data file

Review the file submission

File examples

Related Articles