Checkout - SureCart

These hooks allow you to respond to checkout events and customize the checkout experience.

Actions

Actions are triggered during the checkout process and when orders are confirmed. This is at the end, after payment is successuflly confirmed by the processor.

`surecart/checkout_confirmed`

Fired after an order is confirmed and all purchases have been processed. Use this for post-checkout operations like analytics tracking, external notifications, or custom logging.

Action Parameters

Show properties

\SureCart\Models\Checkout

The checkout model object containing order details.

\WP_REST_Request

The REST API request object.

add_action( 'surecart/checkout_confirmed', function( $checkout, $request ) {
    // Fetch the checkout with customer relation loaded.
    $checkout = \SureCart\Models\Checkout::with(['customer'])->find( $checkout->id );

    // Access order details
    $order_id = $checkout->id;
    $total = $checkout->total_amount;

    // Track conversion
    if ( function_exists( 'track_conversion' ) ) {
        track_conversion( $order_id, $total );
    }

    // Send to external system
    wp_remote_post( 'https://api.example.com/orders', [
        'body' => [
            'order_id' => $order_id,
            'total' => $total,
            'customer_email' => $checkout->customer->email,
        ]
    ]);
}, 10, 2 );

Filters

Form Validation

These filters run during the finalize step of checkout, before the order is submitted. Use them to validate form data and prevent checkout if validation fails.

`surecart/checkout/validate`

Add custom server-side validation to checkout forms. This filter runs during the finalize step, after client-side validation passes but before the order is submitted to the payment processor.

Filter Parameters

Show properties

\WP_Error

Error object to add validation errors to. Add errors using $errors->add( $code, $message ).

array

All checkout form data including email, name, billing_address, shipping_address, metadata, line_items, and custom fields.

\WP_REST_Request

The REST API request object. Use $request->get_param( 'key' ) to access specific parameters.

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    // Require a custom field
    if ( empty( $args['metadata']['company_name'] ) ) {
        $errors->add( 'company_required', 'Company name is required.' );
    }

    return $errors;
}, 10, 3 );

Validate Email Domain

Block specific email domains from purchasing:

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $blocked_domains = [ 'tempmail.com', 'throwaway.com', 'mailinator.com' ];

    $email = $args['email'] ?? '';
    $domain = substr( strrchr( $email, '@' ), 1 );

    if ( in_array( $domain, $blocked_domains, true ) ) {
        $errors->add(
            'blocked_email',
            'Please use a valid email address. Temporary email addresses are not allowed.'
        );
    }

    return $errors;
}, 10, 3 );

Validate Custom Fields

Validate custom form fields added to your checkout:

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    // Get custom fields from metadata
    $metadata = $args['metadata'] ?? [];

    // Validate age requirement
    if ( isset( $metadata['your_age'] ) ) {
        if ( $metadata['your_age'] < 18 ) {
            $errors->add( 'age_restriction', 'You must be 18 or older to purchase.' );
        }
    }

    return $errors;
}, 10, 3 );

Validate Based on Form ID

Apply validation only to specific checkout forms:

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $form_id = $request->get_param( 'form_id' );

    // Only validate on specific form
    if ( $form_id !== 123 ) {
        return $errors;
    }

    // Form-specific validation
    if ( empty( $args['metadata']['license_number'] ) ) {
        $errors->add( 'license_required', 'Professional license number is required.' );
    }

    return $errors;
}, 10, 3 );

User Creation

Control whether newly created users are automatically logged in after checkout.

// Disable auto-login for new users
add_filter( 'surecart/checkout/auto-login-new-user', '__return_false' );

Display

`surecart_checkout_show_converted_total`

Control whether converted currency totals are shown when using currency conversion.

add_filter( 'surecart_checkout_show_converted_total', function( $show, $checkout ) {
    // Don't show converted total for small orders
    if ( $checkout->total_amount < 1000 ) { // Less than $10
        return false;
    }
    return $show;
}, 10, 2 );

`sc_checkout_price_selector_first_price_as_default`

Control whether the first price is selected by default in price selectors.

add_filter( 'sc_checkout_price_selector_first_price_as_default', '__return_false' );

Payment Mode

`surecart/payments/mode`

Filter the payment mode (live/test). Useful for testing or staging environments.

add_filter( 'surecart/payments/mode', function( $mode ) {
    // Force test mode for admins
    if ( current_user_can( 'manage_options' ) ) {
        return 'test';
    }
    return $mode;
} );

// Or force test mode on staging
add_filter( 'surecart/payments/mode', function( $mode ) {
    if ( wp_get_environment_type() === 'staging' ) {
        return 'test';
    }
    return $mode;
} );

JavaScript Filters

SureCart provides JavaScript filters using the WordPress hooks system (wp.hooks) to customize the Stripe Payment Element. These filters allow you to modify payment method order, wallet visibility, legal terms display, and billing fields.

These filters use the @wordpress/hooks package, which is automatically available on pages with SureCart checkout.

Payment Method Order

Use surecart_stripe_payment_element_payment_method_order to reorder the payment methods displayed in Stripe’s Payment Element.

wp.hooks.addFilter(
  "surecart_stripe_payment_element_payment_method_order",
  "my-customization",
  (paymentMethodOrder, checkout) => {
    // Return an array of payment method types in your preferred order
    return ["card", "us_bank_account", "klarna"];
  }
);

See the Stripe Payment Element documentation for available payment method types.

Wallet Visibility

Use surecart_stripe_payment_element_wallets to control the visibility of digital wallets like Apple Pay, Google Pay, and Link within the Payment Element.

wp.hooks.addFilter(
  "surecart_stripe_payment_element_wallets",
  "my-customization",
  (wallets, checkout) => {
    return {
      applePay: "auto", // 'auto' | 'never'
      googlePay: "auto", // 'auto' | 'never'
      link: "never", // 'auto' | 'never'
    };
  }
);

See the Stripe wallets documentation for more options.

Legal Terms Display

Use surecart_stripe_payment_element_terms to manage the display of mandates and other legal agreements within the Payment Element. By default, these are shown only when necessary.

wp.hooks.addFilter(
  "surecart_stripe_payment_element_terms",
  "my-customization",
  (terms, checkout) => {
    return {
      card: "never", // Hide card terms
      usBankAccount: "always", // Always show bank account terms
    };
  }
);

See the Stripe terms documentation for available options.

Billing Fields

Use surecart_stripe_payment_element_fields to control which billing address fields are displayed within the Stripe Payment Element. This is useful when you’re already collecting billing information elsewhere in your checkout form.

wp.hooks.addFilter(
  "surecart_stripe_payment_element_fields",
  "my-customization",
  (fields) => {
    return {
      billingDetails: {
        name: "never",
        email: "never",
        address: {
          line1: "never",
          line2: "never",
          city: "never",
          state: "never",
          postalCode: "never",
          country: "never",
        },
      },
    };
  }
);

To show specific fields, simply remove them from the object or set them to 'auto'. For example, to hide all fields except country:

wp.hooks.addFilter(
  "surecart_stripe_payment_element_fields",
  "my-customization",
  (fields) => {
    return {
      billingDetails: {
        address: {
          line1: "never",
          line2: "never",
          city: "never",
          state: "never",
          postalCode: "never",
          // country is not set, so it will display
        },
      },
    };
  }
);

See the Stripe fields documentation for all available options.

Address Countries

Use surecart_address_countries to customize the list of countries available in address fields. You can add, remove, reorder, or translate country names.

To add custom JavaScript filters to your site, you can use plugins like Simple Custom CSS and JS. Be sure to load scripts in the footer for checkout page compatibility.

wp.hooks.addFilter(
  "surecart_address_countries",
  "my-customization",
  (countries) => {
    // Return only specific countries
    return [
      { value: "US", label: "United States" },
      { value: "CA", label: "Canada" },
      { value: "GB", label: "United Kingdom" },
    ];
  }
);

Each country object must include both value (ISO country code) and label (display name) properties.

Address Regions

Use surecart_address_regions to customize the regions (states, provinces, etc.) available for specific countries. You can add, remove, or translate region names.

wp.hooks.addFilter(
  "surecart_address_regions",
  "my-customization",
  (regions, country) => {
    // Add custom regions for Taiwan
    if (country === "TW") {
      regions.push(
        { value: "test-region-one", label: "Test Region 1" },
        { value: "test-region-two", label: "Test Region 2" }
      );
    }
    return regions;
  }
);

The filter receives the current regions array and the country code. Each region object must include both value and label properties.

Use Cases

Analytics & Conversion Tracking

add_action( 'surecart/checkout_confirmed', function( $checkout, $request ) {
    // Fetch the checkout with customer relation loaded.
    $checkout = \SureCart\Models\Checkout::with(['customer'])->find( $checkout->id );

    // Google Analytics 4 - Server-side tracking
    $measurement_id = 'G-XXXXXXXXXX';
    $api_secret = 'your-api-secret';

    wp_remote_post( "https://www.google-analytics.com/mp/collect?measurement_id={$measurement_id}&api_secret={$api_secret}", [
        'body' => json_encode([
            'client_id' => $checkout->customer->id,
            'events' => [[
                'name' => 'purchase',
                'params' => [
                    'transaction_id' => $checkout->id,
                    'value' => $checkout->total_amount / 100,
                    'currency' => $checkout->currency,
                ]
            ]]
        ])
    ]);
}, 10, 2 );

Send to Slack

add_action( 'surecart/checkout_confirmed', function( $checkout, $request ) {
    // Fetch the checkout with customer relation loaded.
    $checkout = \SureCart\Models\Checkout::with(['customer'])->find( $checkout->id );

    $webhook_url = 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL';

    wp_remote_post( $webhook_url, [
        'body' => json_encode([
            'text' => sprintf(
                '🎉 New order! %s just purchased for %s',
                $checkout->customer->email,
                sc_format_amount( $checkout->total_amount, $checkout->currency )
            )
        ]),
        'headers' => [
            'Content-Type' => 'application/json'
        ]
    ]);
}, 10, 2 );

Validate Minimum Order Amount

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $checkout = $request->get_param( 'checkout' );

    if ( isset( $checkout['total_amount'] ) && $checkout['total_amount'] < 500 ) {
        $errors->add(
            'minimum_order',
            'Minimum order amount is $5.00.'
        );
    }

    return $errors;
}, 10, 3 );

Restrict Purchases by Country

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $blocked_countries = [ 'XX', 'YY' ]; // Country codes to block

    $billing_address = $args['billing_address'] ?? [];
    $country = $billing_address['country'] ?? '';

    if ( in_array( $country, $blocked_countries, true ) ) {
        $errors->add(
            'country_blocked',
            'Sorry, we cannot ship to your country.'
        );
    }

    return $errors;
}, 10, 3 );

Require Terms Acceptance

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $metadata = $args['metadata'] ?? [];

    if ( empty( $metadata['accept_terms'] ) || $metadata['accept_terms'] !== 'yes' ) {
        $errors->add(
            'terms_required',
            'You must accept the terms and conditions to continue.'
        );
    }

    return $errors;
}, 10, 3 );

Validate Tax Identifier

Use the built-in tax_identifier field to validate VAT/tax ID numbers:

add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
    $tax_identifier = $args['tax_identifier'] ?? [];
    $billing_address = $args['billing_address'] ?? [];

    // Require tax ID for EU business customers
    $eu_countries = [ 'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE' ];

    $country = $billing_address['country'] ?? '';

    if ( in_array( $country, $eu_countries, true ) ) {
        // Check if tax identifier number is provided
        if ( empty( $tax_identifier['number'] ) ) {
            $errors->add( 'tax_id_required', 'A VAT number is required for EU business purchases.' );
        }
    }

    return $errors;
}, 10, 3 );

Force Test Mode for Non-Production

add_filter( 'surecart/payments/mode', function( $mode ) {
    // Always use test mode unless on production
    $allowed_hosts = [ 'www.example.com', 'example.com' ];

    if ( ! in_array( $_SERVER['HTTP_HOST'], $allowed_hosts ) ) {
        return 'test';
    }

    return $mode;
} );

JavaScript Filter Use Cases

Sell Only to Specific Countries

Restrict your checkout to only allow purchases from certain countries:

wp.hooks.addFilter(
  "surecart_address_countries",
  "my-customization",
  (countries) => {
    // Only sell to North American countries
    const allowedCountries = ["US", "CA", "MX"];
    return countries.filter((country) =>
      allowedCountries.includes(country.value)
    );
  }
);

Exclude Specific Countries

Remove certain countries from the dropdown while keeping all others:

wp.hooks.addFilter(
  "surecart_address_countries",
  "my-customization",
  (countries) => {
    // Exclude countries you don't ship to
    const excludedCountries = ["RU", "BY", "KP"];
    return countries.filter(
      (country) => !excludedCountries.includes(country.value)
    );
  }
);

Change County Name Translations

Change the transled country names to something different.

wp.hooks.addFilter(
  "surecart_address_countries",
  "my-customization",
  (countries) => {
    // Spanish translations for common countries
    const translations = {
      US: "Estados Unidos",
      CA: "Canadá",
      MX: "México",
      ES: "España",
      GB: "Reino Unido",
      FR: "Francia",
      DE: "Alemania",
    };

    return countries.map((country) => ({
      value: country.value,
      label: translations[country.value] || country.label,
    }));
  }
);

Prioritize Common Countries

Move your most common customer countries to the top of the list:

wp.hooks.addFilter(
  "surecart_address_countries",
  "my-customization",
  (countries) => {
    const priorityCountries = ["US", "CA", "GB", "AU"];

    // Separate priority and other countries
    const priority = countries.filter((c) =>
      priorityCountries.includes(c.value)
    );
    const others = countries.filter(
      (c) => !priorityCountries.includes(c.value)
    );

    // Sort priority countries in specified order
    priority.sort(
      (a, b) =>
        priorityCountries.indexOf(a.value) - priorityCountries.indexOf(b.value)
    );

    return [...priority, ...others];
  }
);

Prioritize Card Payments

Show card payment first for faster checkout:

wp.hooks.addFilter(
  "surecart_stripe_payment_element_payment_method_order",
  "my-customization",
  (paymentMethodOrder, checkout) => {
    return ["card", "apple_pay", "google_pay", "klarna", "afterpay_clearpay"];
  }
);

Disable Link Wallet for Subscriptions

Hide Stripe Link for recurring payments:

wp.hooks.addFilter(
  "surecart_stripe_payment_element_wallets",
  "my-customization",
  (wallets, checkout) => {
    // Check if checkout contains a subscription
    const hasSubscription = checkout?.line_items?.data?.some(
      (item) => item.price?.recurring_interval
    );

    if (hasSubscription) {
      return {
        ...wallets,
        link: "never",
      };
    }

    return wallets;
  }
);

Show Bank Terms for High-Value Orders

Always display ACH terms for orders over a certain amount:

wp.hooks.addFilter(
  "surecart_stripe_payment_element_terms",
  "my-customization",
  (terms, checkout) => {
    // Show bank account terms for orders over $500
    if (checkout?.total_amount > 50000) {
      return {
        ...terms,
        usBankAccount: "always",
      };
    }
    return terms;
  }
);

Modifying Templates

You can customize the HTML output of SureCart blocks using WordPress’s render_block filter and the HTML Tag Processor.

Templates

Learn how to modify block HTML, add custom attributes, wrap content, and inject elements into templates.

Cart

Customize cart icon and visibility.

Login

Customize login redirects and authentication.

Purchases

Hook into individual purchase events.

Orders

Hook into order and payment events.

Templates

Modify blocks, shortcodes, and inject content.

​Actions

​surecart/checkout_confirmed

​Filters

​Form Validation

​surecart/checkout/validate

Validate Email Domain

Validate Custom Fields

Validate Based on Form ID

​User Creation

​surecart/checkout/auto-login-new-user

​Display

​surecart_checkout_show_converted_total

​sc_checkout_price_selector_first_price_as_default

​Payment Mode

​surecart/payments/mode

​JavaScript Filters

​Payment Method Order

​Wallet Visibility

​Legal Terms Display

​Billing Fields

​Address Countries

​Address Regions

​Use Cases

​Analytics & Conversion Tracking

​Send to Slack

​Validate Minimum Order Amount

​Restrict Purchases by Country

​Require Terms Acceptance

​Validate Tax Identifier

​Force Test Mode for Non-Production

​JavaScript Filter Use Cases

​Sell Only to Specific Countries

​Exclude Specific Countries

​Change County Name Translations

​Prioritize Common Countries

​Prioritize Card Payments

​Disable Link Wallet for Subscriptions

​Show Bank Terms for High-Value Orders

​Modifying Templates

Templates

​Related

Cart

Login

Purchases

Orders

Templates

Actions

`surecart/checkout_confirmed`

Filters

Form Validation

`surecart/checkout/validate`

User Creation

`surecart/checkout/auto-login-new-user`

Display

`surecart_checkout_show_converted_total`

`sc_checkout_price_selector_first_price_as_default`

Payment Mode

`surecart/payments/mode`

JavaScript Filters

Payment Method Order

Wallet Visibility

Legal Terms Display

Billing Fields

Address Countries

Address Regions

Use Cases

Analytics & Conversion Tracking

Send to Slack

Validate Minimum Order Amount

Restrict Purchases by Country

Require Terms Acceptance

Validate Tax Identifier

Force Test Mode for Non-Production

JavaScript Filter Use Cases

Sell Only to Specific Countries

Exclude Specific Countries

Change County Name Translations

Prioritize Common Countries

Prioritize Card Payments

Disable Link Wallet for Subscriptions

Show Bank Terms for High-Value Orders

Modifying Templates

Related