gform_stripe_customer_id

Description

The gform_stripe_customer_id filter can be used to specify an existing customer ID to be used when processing the submission.

Usage

The hook, which would run for all Stripe feeds, can be used as:

add_filter( 'gform_stripe_customer_id', 'your_function_name', 10, 4 );

Parameters

ParameterTypeDescription
$customer_idstringThe Stripe customer ID. Defaults to an empty string, causing a new customer to be created.
$feedFeed ObjectThe Stripe feed currently being processed.
$entryEntry ObjectThe entry currently being processed.
$formForm ObjectThe form currently being processed.

Examples

ID from user meta.

The following example shows how, if the user is logged in, you can retrieve the customer id from the user meta. See the gform_stripe_customer_after_create hook for an example showing how the customer id can be saved to the user meta.

add_filter( 'gform_stripe_customer_id', 'get_stripe_customer_id', 10, 4 );
function get_stripe_customer_id( $customer_id ) {

    if ( is_user_logged_in() ) {
        $user_id      = get_current_user_id();
        $customer_id  = get_user_meta( $user_id, '_stripe_customer_id', true );
        gf_stripe()->log_debug( __METHOD__ . "(): Retrieved Stripe Customer ID {$customer_id} from WP user ID {$user_id}" );
    }

    return $customer_id;
}

Create a new customer.

See the Stripe API documentation for creating a customer for the supported parameters. You edit to edit $feed_names to include the name of the feed(s) which you want to trigger the snippet, and the id of the Name and Phone fields (or remove the lines for them).

add_filter( 'gform_stripe_customer_id', function ( $customer_id, $feed, $entry, $form ) {

    $feed_name = rgars( $feed, 'meta/feedName' );

    gf_stripe()->log_debug( 'gform_stripe_customer_id: Running for Feed: ' . $feed_name );

    // Define the feed names this code should run for.
    $feed_names = array( 'feed name one', 'feed name two' );

    // Abort if processed by a different feed OR it's not a product-and-services feed.
    if ( rgars( $feed, 'meta/transactionType' ) !== 'product' || ! in_array( $feed_name, $feed_names ) ) {
        return $customer_id;
    }

    if ( empty( $customer_id ) ) {

        $response = gf_stripe()->get_stripe_js_response();

        if ( ! empty( $response->id ) && substr( $response->id, 0, 3 ) === 'pi_' ) {
            try {
                $intent = \Stripe\PaymentIntent::retrieve( $response->id );
                if ( ! empty( $intent->customer ) ) {
                    gf_stripe()->log_debug(
                        'gform_stripe_customer_id: PaymentIntent has customer: ' . print_r( $intent->customer, true )
                    );
                    return is_object( $intent->customer ) ? $intent->customer->id : $intent->customer;
                }
            } catch ( \Exception $e ) {
                gf_stripe()->log_debug( 'gform_stripe_customer_id: unable to get PaymentIntent; ' . $e->getMessage() );
            }
        }

        $customer_params = array();

        $email_field = rgars( $feed, 'meta/receipt_field' );
        if ( ! empty( $email_field ) && strtolower( $email_field ) !== 'do not send receipt' ) {
            $customer_params['email'] = gf_stripe()->get_field_value( $form, $entry, $email_field );
        }

        // Optional - Customer name from Name field ID 8.
        $customer_params['name'] = rgar( $entry, '8.3' ) . ' ' . rgar( $entry, '8.6' );
        gf_stripe()->log_debug( __METHOD__ . '(): Name: ' . $customer_params['name'] );

        // Optional - Customer phone from Phone field ID 5.
        $customer_params['phone'] = rgar( $entry, '5' );
        gf_stripe()->log_debug( __METHOD__ . '(): Phone: ' . $customer_params['phone'] );

        $customer    = gf_stripe()->create_customer( $customer_params, $feed, $entry, $form );
        $customer_id = $customer->id;

        gf_stripe()->log_debug( 'gform_stripe_customer_id: Returning Customer ID: ' . $customer_id );
    }

    return $customer_id;
}, 10, 4 );

Group transactions by email.

The following example shows how to group transactions and subscriptions associated with the same email address under a single Stripe customer. If a customer with the submitted email address already exists in Stripe, their customer ID is returned. If no match is found, an empty string is returned, and a new customer is created.

add_filter( 'gform_stripe_customer_id', function( $customer_id, $feed, $entry, $form ) {
    // Loading Stripe API.
    $api = (new Gravity_forms\Gravity_Forms_Stripe\Elements\Elements_Handler())->get_api( $feed );
    // Getting email based on mapped email field in the feed.
    $email = gf_stripe()->get_field_value( $form, $entry, rgars( $feed, 'meta/customerInformation_email' ) );
    // Searching customers by email using the Stripe API (will return the first customer that matches the email).
    $customer = $api->get_customer_by_email( $email );
    // If a customer is found, return the customer ID, otherwise return empty string to create a new customer.
    return $customer ? $customer->id : '';
}, 10, 4 );

Placement

This code can be used in the functions.php file of the active theme, a custom functions plugin, a custom add-on, or with a code snippets plugin.

See also the PHP section in this article: Where Do I Put This Code?

Since

This hook was added in Stripe version 2.1.

Source Code

$customer_id = apply_filters( 'gform_stripe_customer_id', $customer_id, $feed, $entry, $form );

This hook is located in GFStripe::get_customer() in class-gf-stripe.php.