suredonation_import_donation_row Filter Hook

Overview

The suredonation_import_donation_row filter allows developers to modify a donation record after it has been mapped and sanitized from a CSV file, but before the donation is inserted into the database.

This is useful when the standard SureDonation importer does not support a field from your CSV or when you need to customize an imported donation value.

SureDonation Pro uses this filter to populate subscription-related fields such as subscription_id, subscription_status, and donation_type.

When to Use This Filter

Use this filter when you need to:

• Map custom CSV columns to SureDonation donation fields.
• Add values that are not handled by the default importer.
• Modify existing donation values before insertion.
• Import legacy transaction references.
• Extend the standard donation import process without replacing the importer.

Filter Signature

apply_filters( 'suredonation_import_donation_row', $donation, $data );

apply_filters( 'suredonation_import_donation_row', $donation, $data );

Parameters

$donation

The donation array can contain fields such as:

• amount
• currency
• transaction_id
• gateway
• payment_status
• payment_mode
• donor_name
• donor_email
• donor_phone
• is_anonymous
• donation_type
• donor_comment
• ip_address
• import_source
• import_source_id
• created_at

The created_at field is included when the CSV provides a valid date.

Return Value

Return the modified donation array.

return $donation;

If the filter callback returns a non-array value, SureDonation discards that result and uses the original unfiltered donation row.

Basic Usage

add_filter( 'suredonation_import_donation_row', 'your_custom_function',  10,  2);

function your_custom_function( $donation, $data ) {

    // Modify the donation data here.

    return $donation;

}

add_filter( 'suredonation_import_donation_row', 'your_custom_function',  10,  2);

function your_custom_function( $donation, $data ) {

    // Modify the donation data here.

    return $donation;

}

Example: Map a Legacy Reference

Suppose your CSV contains a legacy_reference column that should be used as the SureDonation transaction ID.

add_filter(

    'suredonation_import_donation_row',

    'mysite_map_legacy_reference',

    10,

    2

);

function mysite_map_legacy_reference( $donation, $data ) {

    // The legacy CSV carries its own reference column.

    if ( ! empty( $data['legacy_reference'] ) ) {

        $donation['transaction_id'] = sanitize_text_field(

            $data['legacy_reference']

        );

    }

    return $donation;

}

add_filter(

    'suredonation_import_donation_row',

    'mysite_map_legacy_reference',

    10,

    2

);

function mysite_map_legacy_reference( $donation, $data ) {

    // The legacy CSV carries its own reference column.

    if ( ! empty( $data['legacy_reference'] ) ) {

        $donation['transaction_id'] = sanitize_text_field(

            $data['legacy_reference']

        );

    }

    return $donation;

}

How the Example Works

1. SureDonation reads the CSV row.
2. The standard importer maps and sanitizes the supported fields.
3. The filter receives the prepared donation data.
4. The callback checks for legacy_reference.
5. The legacy value is sanitized and assigned to transaction_id.
6. The modified donation is inserted into the database.

Example: Map a Custom CSV Field

You can also map another CSV column to an existing SureDonation field.

add_filter(  'suredonation_import_donation_row',  'mysite_map_custom_comment',  10,  2);

function mysite_map_custom_comment( $donation, $data ) {

    if ( ! empty( $data['additional_notes'] ) ) {

        $donation['donor_comment'] = sanitize_textarea_field(

            $data['additional_notes']

        );

    }

    return $donation;

}

add_filter(  'suredonation_import_donation_row',  'mysite_map_custom_comment',  10,  2);

function mysite_map_custom_comment( $donation, $data ) {

    if ( ! empty( $data['additional_notes'] ) ) {

        $donation['donor_comment'] = sanitize_textarea_field(

            $data['additional_notes']

        );

    }

    return $donation;

}

Example: Add Subscription Data

This filter can be used to add subscription-related values when your imported CSV contains the required information.

add_filter( 'suredonation_import_donation_row',   'mysite_map_subscription_data',  10,   2);

function mysite_map_subscription_data( $donation, $data ) {

    if ( ! empty( $data['subscription_id'] ) ) {

        $donation['subscription_id'] = sanitize_text_field(

            $data['subscription_id']

        );

        $donation['subscription_status'] = ! empty(

            $data['subscription_status']

        )

            ? sanitize_text_field( $data['subscription_status'] )

            : 'active';

        $donation['donation_type'] = 'recurring';

    }

    return $donation;

}

add_filter( 'suredonation_import_donation_row',   'mysite_map_subscription_data',  10,   2);

function mysite_map_subscription_data( $donation, $data ) {

    if ( ! empty( $data['subscription_id'] ) ) {

        $donation['subscription_id'] = sanitize_text_field(

            $data['subscription_id']

        );

        $donation['subscription_status'] = ! empty(

            $data['subscription_status']

        )

            ? sanitize_text_field( $data['subscription_status'] )

            : 'active';

        $donation['donation_type'] = 'recurring';

    }

    return $donation;

}

Import Flow

The filter runs near the end of the donation import process:

1. SureDonation reads a CSV row.
2. The row is mapped to SureDonation fields.
3. Standard fields are sanitized.
4. The suredonation_import_donation_row filter runs.
5. Your callback can add or modify donation data.
6. SureDonation inserts the resulting donation using Donations::add().
7. The donation insertion process continues.

Data Sanitization

All standard fields have already been sanitized when this filter runs.

However, any data that you add or overwrite is your responsibility to sanitize.

For example:

$donation['transaction_id'] = sanitize_text_field(

    $data['legacy_reference']

);

$donation['transaction_id'] = sanitize_text_field(

    $data['legacy_reference']

);

Do not assume that custom CSV fields have already been sanitized.

Important: Preserve Import Metadata

Two fields are important for import tracking and re-import de-duplication:

import_source

import_source_id

The default importer uses:

• import_source = suredonation
• import_source_id = Source row identifier

Avoid changing or removing these fields unless you understand how the replacement values will affect re-import handling.

When to Use This vs. a Custom Mapper

Use suredonation_import_donation_row when you only need to modify or extend the donation data.

For example:

CSV row

   ↓

Standard mapper

   ↓

suredonation_import_donation_row

   ↓

Database

If you need to completely change how a migration phase processes records, consider registering a custom mapper through: suredonation_import_phase_mappers

Related Hooks

• Suredonation_import_donation_inserted: Runs after an imported donation has been inserted.
• Suredonation_import_phase_mappers: Allows developers to register custom import phase mappers.
• Suredonation_create_donation_data: Filters donation data when creating a donation.
• Suredonation_export_one_time_only: Controls one-time donation export behavior.