Filter uncanny-automator

automator_surecart_billing_tokens_v2

Filters SureCart billing tokens before they are used for payments.

add_filter( 'automator_surecart_billing_tokens_v2', $callback, 10, 1 );

Description

Fires to define and register available SureCart billing tokens for use in Uncanny Automator recipes. Developers can add custom billing tokens or modify existing ones by returning an array of token definitions from this filter. Ensure each token definition includes 'tokenId', 'tokenName', and 'tokenType'.

Usage

add_filter( 'automator_surecart_billing_tokens_v2', 'your_function_name', 10, 1 );

Parameters

$tokens (mixed): This parameter contains an array of billing tokens, each representing a piece of customer billing information that can be used in automations.

Return Value

The filtered value.

Examples

<?php
/**
 * Add a custom token to the SureCart billing tokens for Uncanny Automator.
 *
 * This example demonstrates how to add a new token representing the customer's
 * billing email to the available tokens for SureCart billing actions within
 * Uncanny Automator.
 *
 * @param array $tokens The existing array of SureCart billing tokens.
 * @return array The modified array of SureCart billing tokens.
 */
function my_custom_surecart_billing_tokens( $tokens ) {

	// Check if the BILLING_EMAIL token is not already present to avoid duplicates.
	if ( ! array_key_exists( 'BILLING_EMAIL', $tokens ) ) {
		$tokens['BILLING_EMAIL'] = array(
			'tokenId'   => 'BILLING_EMAIL',
			'tokenName' => esc_html__( "Customer's billing email", 'your-text-domain' ),
			'tokenType' => 'email', // Use 'email' for validation and specific handling.
		);
	}

	return $tokens;
}

// Add the filter to the 'automator_surecart_billing_tokens_v2' hook.
// The priority '10' is the default, and '1' indicates the function accepts one argument.
add_filter( 'automator_surecart_billing_tokens_v2', 'my_custom_surecart_billing_tokens', 10, 1 );
?>

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/integrations/surecart/tokens/surecart-tokens-new-framework.php:380

public function billing_tokens() {

		$tokens = array(
			array(
				'tokenId'   => 'BILLING_NAME',
				'tokenName' => esc_html_x( "Customer's name", 'Surecart', 'uncanny-automator' ),
				'tokenType' => 'text',
			),
			array(
				'tokenId'   => 'BILLING_EMAIL',
				'tokenName' => esc_html_x( "Customer's email", 'Surecart', 'uncanny-automator' ),
				'tokenType' => 'text',
			),
			array(
				'tokenId'   => 'BILLING_PHONE',
				'tokenName' => esc_html_x( "Customer's phone", 'Surecart', 'uncanny-automator' ),
				'tokenType' => 'text',
			),
		);

		return apply_filters( 'automator_surecart_billing_tokens_v2', $tokens );
	}