suredonation_create_donation_data Filter Hook

Overview

The suredonation_create_donation_data filter allows developers to modify the donation data generated during a REST API donation creation request, immediately before the record is inserted into the database.

The filtered array is passed directly to SureDonation’s donation creation process. This makes the hook useful for adding or modifying custom donation data, including fields introduced by an extension.

When to Use This Filter

Use this filter when you need to:

• Add custom data to a donation record.
• Modify existing donation fields before insertion.
• Map additional REST request parameters to donation data.
• Store information from external sources such as UTM parameters.
• Extend SureDonation with custom database columns.

Filter Signature

apply_filters( 'suredonation_create_donation_data', $donation_data, $request );

apply_filters( 'suredonation_create_donation_data', $donation_data, $request );

Parameters

Donation Data

The $donation_data array contains fields such as:

Return Value

Return the modified donation data array.

return $donation_data;

The returned array is passed directly to the donation insertion process.

Basic Usage

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

function your_custom_function( $donation_data, $request ) {

// Modify the donation data here.

return $donation_data;

}

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

function your_custom_function( $donation_data, $request ) {

// Modify the donation data here.

return $donation_data;

}

Example: Store a UTM Source

The following example reads the utm_source parameter from the REST request and stores it in the donor comment.

add_filter( 'suredonation_create_donation_data', 'mysite_tag_source', 10, 2);

function mysite_tag_source( $donation_data, $request ) {

$source = $request->get_param( 'utm_source' );

if ( $source ) {

$donation_data['donor_comment'] =

'Source: ' . sanitize_text_field( $source );

}

return $donation_data;

}

add_filter( 'suredonation_create_donation_data', 'mysite_tag_source', 10, 2);

function mysite_tag_source( $donation_data, $request ) {

$source = $request->get_param( 'utm_source' );

if ( $source ) {

$donation_data['donor_comment'] =

'Source: ' . sanitize_text_field( $source );

}

return $donation_data;

}

Example: Add a Custom Field

If an extension has added a custom column to the donations table, the filter can be used to populate it.

add_filter( 'suredonation_create_donation_data', 'mysite_add_campaign_source', 10, 2);

function mysite_add_campaign_source( $donation_data, $request ) {

$source = $request->get_param( 'campaign_source' );

if ( $source ) {

$donation_data['campaign_source'] =

sanitize_text_field( $source );

}

return $donation_data;

}

add_filter( 'suredonation_create_donation_data', 'mysite_add_campaign_source', 10, 2);

function mysite_add_campaign_source( $donation_data, $request ) {

$source = $request->get_param( 'campaign_source' );

if ( $source ) {

$donation_data['campaign_source'] =

sanitize_text_field( $source );

}

return $donation_data;

}

Donation Creation Flow

The filter runs after SureDonation has assembled the donation data but before the record is inserted.

REST create-donation request

          ↓

Validate request

          ↓

Build donation data

          ↓

suredonation_create_donation_data

          ↓

Custom data added or existing data modified

          ↓

Donations::add()

          ↓

Donation stored in database

          ↓

suredonation_donation_created

Data Sanitization

The returned array is passed directly to the donation insertion process.

If you add or modify values, sanitize them before returning the array.

For example:

$source = sanitize_text_field(

$request->get_param( 'utm_source' )

);

$source = sanitize_text_field(

$request->get_param( 'utm_source' )

);

Do not store raw user-provided values without appropriate sanitization or validation.

Related Hooks

• suredonation_update_donation_data: Filters donation data before an existing donation is updated through the REST API.
• suredonation_donation_created: Fires after a new donation has been created.