Functions

Estimated reading: 57 minutes 1350 views

buycred_complete_pending_payment

Package: mycred/purchase Category: Functions

Description

This function will process a pending point purchase and “complete” it by paying the buyer the point they purchased. This processing is done using the payment gateway set in the pending payment object, by using the gateways complete_payment() method.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(bool) Returns TRUE if the transaction was completed successfully else FALSE.

Parameters

	Param	Type	Required	Description
function `buycred_complete_pending_payment(`
	`$payment_id`	INT or STRING	Yes	The pending payment public ID in string format or the WordPress post object ID.
`) { ... }`

buycred_gateway

Package: mycred/purchase Category: Functions

Description

This function will construct a given buyCRED Payment Gateway.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(bool | class) Returns either false or the given payment gateway class.

Parameters

	Param	Type	Required	Description
function `buycred_gateway(`
	`$gateway_id`	STRING	Yes	The buyCRED Payment Gateway ID.
`) { ... }`

buycred_get_pending_payment

Package: mycred/purchase Category: Functions

Description

This function retrieves the buyCRED pending payment object based on a given pending payment ID.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(bool | object) Returns either the payment object or FALSE if the payment is not found.

Parameters

	Param	Type	Required	Description
function `buycred_get_pending_payment(`
	`$payment_id`	STRING	Yes	The buyCRED pending payment ID.
`) { ... }`

Pending Payment Object Example

				
					Std Object
(
    [payment_id] => 1
    [public_id] => 'ABC123'
    [point_type] => 'mycred_default'
    [amount] => 250
    [cost] => 100
    [currency] => 'USD'
    [buyer_id] => 2
    [recipient_id] => 2
    [gateway_id] => 'paypal-standard'
    [transaction_id] => ''
    [cancel_url] => 'https://www.yourwebsite.com/cancelled/'
    [pay_now_url] => 'https://www.yourwebsite.com/buy/?mycred_buy=paypal-standard&revisit=ABC123'
)

Example

Example 1: Basic usage example

				
					$payment_id      = sanitize_text_field( $_GET['id'] );
$pending_payment = buycred_get_pending_payment( $payment_id );

if ( $pending_payment !== false ) {
	// Payment was found.
}

buycred_get_pending_payment_id

Package: mycred/purchase Category: Functions

Description

This function attempts to get the WordPress post object ID for a given buyCRED pending payment ID.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(bool | int) Returns either the WordPress post object ID or FALSE on failure.

Parameters

	Param	Type	Required	Description
function `buycred_get_pending_payment_id(`
	`$payment_id`	STRING	Yes	The buyCRED pending payment ID.
`) { ... }`

Example

Example 1: Check if a given ID is a pending payment or not.

				
					$payment_id = sanitize_text_field( $_GET['id'] );
$payment_id = buycred_get_pending_payment_id( $payment_id );

if ( $payment_id !== false ) {
	// This is a pending payment
}

buycred_get_users_pending_payments

Package: mycred/purchase Category: Functions

Description

This function will return all a given users currently pending buyCRED point purchases. The function will return an associative array sorted based on the point types you have enabled to sell.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(array) Returns an associative array of pending payment objects sorted by point type. Returns FALSE if no pending payment exists.

Parameters

	Param	Type	Required	Description
function `buycred_get_users_pending_payments(`
	`$user_id`	INT	Yes	The users numeric WordPress ID.
	`$point_type`	STRING	No	Option to only return pending payments for a given point type.
`) { ... }`

buycred_trash_pending_payment

Package: mycred/purchase Category: Functions

Description

This function will trash a pending buyCRED point purchase payment. This means the buycred_payment post type object will get trashed.

This function is only available if the buyCRED add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the post was trashed else FALSE.

Parameters

	Param	Type	Required	Description
function `buycred_trash_pending_payment(`
	`$payment_id`	INT or STRING	Yes	The pending payment public ID in string format or the WordPress post object ID.
`) { ... }`

mycred

Package: mycred/core Category: Functions

Description

This function constructs and returns the myCRED_Settings object that you can use to access a large variety of methods for processing points or displaying points. Using this function ensures that the class methods are all set to use the same point type and to honour that selected point type’s format and styling setup.

Available since version 1.4

Returns

(object) Returns the myCRED_Settings object.

Parameters

	Param	Type	Required	Description
function `mycred(`
	`$point_type_key`	STRING	No	Used be used when you need to load a custom point type setup instead of the default one.
`) { ... }`

Examples

Example 1: Default usage, accessing the default point type.

				
					$mycred = mycred();

Example 2: Load a custom point type.

				
					$mycred = mycred( 'customtypekey' );

Example 3: Adjust a users balance by removing 10 points from it without a log entry.

				
					$user_id = get_current_user_id();
$mycred  = mycred();

if ( ! $mycred->exclude_user( $user_id ) )
	$mycred->update_users_balance( $user_id, 10 );

mycred_add

Package: mycred/balance Category: Functions

Description

This function allows you to increment a users balance by adding a specific amount to it. Furthermore this function will save a log entry of this adjustment and requires that you provide a reference and a log entry at a bare minimum.

As of version 1.7, this function will return false if the user is set to be excluded. In previous version, this is ignored.

Available since version 1.0

Returns

(bool) true on success or false on declined transaction.

Parameters

	Param	Type	Required	Description
function `mycred_add(`
	`$reference`	STRING	Yes	The reference to log this entry under. You can use your own custom reference or one of the built-in ones.
	`$user_id`	INT	Yes	The ID of the user getting the points.
	`$amount`	INT or FLOAT	Yes	The point amount to give to the user. This can be a positive or negative value.
	`$entry`	STRING	Yes	The entry to save in the log for this adjustment.
	`$ref_id`	INT	No	Optional reference ID to save with the log entry.
	`$data`	STRING	No	Optional data to save with the log entry. Note that if you are supply an array, this will be serialized.
	`$type`	STRING	No	The point type key. Should only be used if you are adjusting a custom point type and not the default one.
`) { ... }`

Examples

Example 1: Add a user 10 points, logged as if it was for an approved comment.

				
					mycred_add( 'approved_comment', $user_id, 10, 'Points for approved comment' );

Example 2: Deduct 5 points of a custom point type from the users account.

				
					mycred_add( 'payment', $user_id, -5, 'Some custom event' );

mycred_add_new_notice

Package: mycred/notice Category: Functions

Description

This function allows you to add a new notification for a specific user. Notifications are shown when the user logs in (if the notice is generated when they are not online) or on the next page reload (if they are logged in).

This function is only available if the Notifications add-on is enabled.

Available since version 1.0

Returns

void

Parameters

	Param	Type	Required	Description
function `mycred_add_new_notice(`
	`$notice`	ARRAY	Yes	An associative array containing the message and the ID of the user that it is intended for.
	`$lifespan`	INT	No	The lifespan of the message. The value is multiplied with the number of seconds there is in a day.
`) { ... }`

mycred_add_user_meta

Package: mycred/core Category: Functions

Description

A wrapper function for add_user_meta, it assures that point related data is saved under the correct meta key structure

Available since version 1.0

Returns

(int | bool) Primary key id for success. FALSE for failure.

Parameters

	Param	Type	Required	Description
function `mycred_add_user_meta(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$meta_key`	STRING	Yes	The meta key id.
	`$end`	STRING	No	Optional ending to append to the meta key id. In certain situation on Multisites, the meta key gets the blogs ID appended. The value of `$end` is then appended after the blog ID, whilst the value of `$meta_key` is before the blog id. On regular WordPress installations `$end` is appended onto `$meta_key`.
	`$value`	STRING	Yes	The meta value.
	`$unique`	BOOL	No	`TRUE` if the meta data is unique or `FALSE` if not. Defaults to `TRUE`.
`) { ... }`

Example

Example 1: Save the total number of times a user has gained points for approved comments.

				
					$user_id       = get_current_user_id();
$comment_count = mycred_count_ref_instances( 'approved_comment', $user_id );

mycred_add_user_meta( $user_id, 'comment_point_count', '', $comment_count );

mycred_assign_badge

Package: mycred/badge Category: Functions

Description

This function assigns a given badge to all users that meet the set requirements.

This function is only available if the Badges add-on is enabled.

Available since version 1.7

Returns

(array) Returns an array of User IDs and the level their reached for this badge.

Parameters

	Param	Type	Required	Description
function `mycred_assign_badge(`
	`$badge_id`	INT	Yes	The badge post object ID.
`) { ... }`

Example

Example 1: Assign a badge and show the number of users that received it.

				
					$badge_id = 1;

$results  = mycred_assign_badge( $badge_id );
printf( '%d users earned this badge.', count( $results ) );

mycred_assign_badge_to_user

Package: mycred/badge Category: Functions

Description

This function assigns a given badge and badge level to a specific user. It is used by other badge assignment functions to connect a badge with a user.

This function is only available if the Badges add-on is enabled. .

Available since version 1.7

Returns

void

Parameters

	Param	Type	Required	Description
function `mycred_assign_badge_to_user(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$badge_id`	INT	Yes	The badge post objects ID.
	`$level`	INT	Yes	The badge level to assign.
`) { ... }`

Example

Example 1: Assign a badge with the id of 1 to the current user.

				
					$user_id  = get_current_user_id();
$badge_id = 1;

mycred_assign_badge_to_user( $user_id, $badge_id, 1 );

mycred_assign_ranks

Package: mycred/rank Category: Functions

Description

This function assigns ranks for a given point type. The function will assign ranks starting with the rank that has the lowest point requirement. Used when clicking on the “Assign users to Ranks” button in the admin area.

Depending on the number of ranks that needs to be assigned and the number of balances on your website, this function can be resource heavy. Should only be used when needed. .

This function is only available if the Ranks add-on is enabled.

Available since version 1.3.2

Returns

(int) Returns the total number of users that successfully received a rank.

Parameters

	Param	Type	Required	Description
function `mycred_assign_ranks(`
	`$point_type`	STRING	No	The point type key. Should only be used if assigning ranks of a custom point type.
`) { ... }`

Example

Example 1: Default usage

				
					$count = mycred_assign_ranks();
printf( '%d ranks were assigned.', $count );

mycred_badge_level_reached

Package: mycred/badge Category: Functions

Description

This function checks if a user has reached the badge requirements set for a given badge. If the requirements have been met, the function will return the level they should have. This function does not assign the badge to the user, it only checks if there should be one.

This function is only available if the Badges add-on is enabled.

Available since version 1.7

Returns

(bool | int) FALSE if the user has not earned the badge yet or if incorrect parameters are provided. If the badge is earned, the badges level is returned instead.

Parameters

	Param	Type	Required	Description
function `mycred_badge_level_reached(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$badge_id`	INT	Yes	The badge post object ID.
`) { ... }`

Example

Example 1: Check if the current user has reached level 4 of a badge.

				
					$badge_id          = 1;
$user_id           = get_current_user_id();
$level_requirement = 4;

$level_reached     = mycred_badge_level_reached( $user_id, $badge_id );

if ( $level_reached !== false && $level_reached >= $level_requirement ) {

	// User has earned the badge and is on level 4 or higher

}

mycred_centralize_log

Package: mycred/core Category: Functions

Description

This function checks if the central log feature is enabled on a Multisite installation. Will return FALSE if Multisite are not being used.

Available since version 1.3

Returns

(bool) TRUE if the central log feature is enabled else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_centralize_log(`
No params
`) { ... }`

Example

Example 1: Default usage

				
					if ( mycred_centralize_log() ) {

	// Central logging is enabled

}

mycred_content_purchase_has_expired

Package: mycred/content Category: Functions

Description

This function will check if a content payment has expired or not.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the purchase as expired else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_content_purchase_has_expired(`
	`$payment`	OBJ	Yes	The payment log entry object.
`) { ... }`

mycred_count_all_ref_instances

Package: mycred/log Category: Functions

Description

This function returns an associative array of references and their individual counts from the log.

Available since version 1.3.3

Returns

(array) Associative array of references and counts.

Parameters

	Param	Type	Required	Description
function `mycred_count_all_ref_instances(`
	`$number`	INT	Yes	The number of references to return a count for. Use `-1` to return all. Defaults to `5`.
	`$order`	STRING	No	Sorting order. Either Ascending (ASC) or Descending (DESC). Defaults to `DESC`.
	`$type`	STRING	No	Option to filter the count based on a point type. Must be either a point type key or the string `all`.
`) { ... }`

Examples

Example 1: Get all references with their count no matter which point type they belong to.

				
					$references = mycred_count_all_ref_instances( -1, 'DESC', 'all' );

if ( ! empty( $references ) ) {
	foreach ( $references as $reference => $count ) {

		echo $reference . ' ' . $count;

	}
}

Example 2: Get the top 10 references for the default point type.

				
					$count = mycred_count_all_ref_instances( 10 );

if ( ! empty( $references ) ) {
	foreach ( $references as $reference => $count ) {

		echo $reference . ' ' . $count;

	}
}

mycred_count_ref_id_instances

Package: mycred/log Category: Functions

Description

Returns the number of times a specific reference, in combination with a reference ID occurs in the log, with the option to filter by user ID or by point type.

Available since version 1.5.3

Returns

(int) Returns the number of found records.

Parameters

	Param	Type	Required	Description
function `mycred_count_ref_id_instances(`
	`$reference`	STRING	Yes	The reference to count.
	`$ref_id`	INT	Yes	The reference ID.
	`$user_id`	INT	No	Option to filter the count by a user ID.
	`$type`	STRING	No	Option to filter results by a particular point type.
`) { ... }`

Example

Example 1: Check if a user has a log entry for receiving points for a particular comment.

				
					$user_id    = 1;
$comment_id = 10;

if ( mycred_count_ref_id_instances( 'approved_comment', $comment_id, $user_id ) > 0 ) {

	// User has received points for this comment

}

mycred_count_ref_instances

Package: mycred/log Category: Functions

Description

Returns the number of times a specific reference occurs in the log, with the option to filter by user ID or by point type.

Remember that transfers always have two log entries, one for the sender and one for the recipient. If you do not filter by a user ID, transfer counts will always be double!

Available since version 1.5.3

Returns

(int) Returns the number of found records.

Parameters

	Param	Type	Required	Description
function `mycred_count_ref_instances(`
	`$reference`	STRING	Yes	The reference to count.
	`$user_id`	INT	No	Option to filter the count by a user ID.
	`$type`	STRING	No	Option to filter results by a particular point type.
`) { ... }`

Examples

Example 1: Count the number of times a user has received points for approved comments

				
					$user_id = 1;
$count   = mycred_count_ref_instances( 'approved_comment', $user_id );

Example 2: Count the number of times points have been spent on paying for a WooCommerce order.

				
					$payments = mycred_count_ref_instances( 'woocommerce_payment' );

mycred_count_users_with_badge

Package: mycred/badge Category: Functions

Description

This function counts the number of users that has a given badge with the option to count badge level.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

(int) The number of users that has a badge or badge level.

Parameters

	Param	Type	Required	Description
function `mycred_count_users_with_badge(`
	`$badge_id`	INT	Yes	The badge post object ID.
	`$level`	INT	No	Option to count a specific level for the given badge.
`) { ... }`

Example

Example 1: Count the number of users that have a badge with the id 1.

				
					$badge_id = 1;
$count    = mycred_count_users_with_badge( $badge_id );

printf( '%d users have earned this badge', $count );

mycred_count_users_without_badge

Package: mycred/badge Category: Functions

Description

This function counts the number of users that has not earned a given badge.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

(int) The number of users that has not earned the badge.

Parameters

	Param	Type	Required	Description
function `mycred_count_users_without_badge(`
	`$badge_id`	INT	Yes	The badge post object ID.
`) { ... }`

Example

Example 1: Count the number of users that have not earned the badge 2 yet.

				
					$badge_id = 2;
$count    = mycred_count_users_without_badge( $badge_id );

printf( '%d users has not yet earned this badge', $count );

mycred_coupon_was_successfully_used

Package: mycred/coupon Category: Functions

Description

This function checks if a coupon was successfully applied or not. Should be used in combination with the mycred_use_coupon function.

This function is only available if the Coupons add-on is enabled.

Available since version 1.7.5

Returns

(bool) TRUE if the coupon was successfully applied else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_coupon_was_successfully_used(`
	`$code`	–	Yes	The results of the mycred_use_coupon function.
`) { ... }`

Example

Example 1: Apply a posted coupon code to the current user.

				
					$user_id = get_current_user_id();
$code    = $_POST['coupon'];

$results = mycred_use_coupon( $code, $user_id );

if ( mycred_coupon_was_successfully_used( $results ) ) {

	// Coupon was successfully used

}
else {

	// Something went wrong

}

mycred_create_chart

Package: mycred/stats Category: Functions

Description

Returns an instance of the myCRED_Chart object for building charts using the Statistics add-on.

This function is only available if the Statistics add-on is enabled.

Available since version 1.8

Returns

(obj) Returns the myCRED_Chart object.

Parameters

	Param	Type	Required	Description
function `mycred_create_chart(`
	`$args`	ARRAY	No	An array of global arguments for charts.
`) { ... }`

Example

Example 1: Generate a pie chart based on the points in circulation on our website.

				
					$global_args = array(
	'title' => 'Points in Circulation'
);

$chart       = mycred_create_chart( $global_args );

// The data to show in the chart.
$data        = mycred_get_circulation_data();

if ( ! empty( $data ) ) {

	echo $chart->pie_chart( $data );

}

mycred_create_new_coupon

Package: mycred/coupon Category: Functions

Description

This function creates a new myCRED Coupon post object. Uses wp_insert_post.

This function is only available if the Coupons add-on is enabled.

Available since version 1.4

Returns

(int | WP_Error) Returns either the coupon post object ID or a WP_Error object.

Parameters

	Param	Type	Required	Description
function `mycred_create_new_coupon(`
	`$args`	ARRAY	Yes	Associative array of coupon arguments.
`) { ... }`

New Coupon Arguments

Argument	Type	Required	Description
`code`	string	No	The coupon code. If not set, the function will generate a random code.
`value`	INT or FLOAT	Yes	The amount of points this coupon generates when redeemed.
`type`	string	No	The point type that this coupon generates. Defaults to the default type key.
`global_max`	INT	No	The maximum number of times the coupon can be redeemed. Defaults to 1. Can not be zero!
`user_max`	INT	No	The maximum number of times the coupon can be redeemed by a single user. Defaults to 1.
`min_balance`	INT or FLOAT	No	Optional minimum balance requirement for redeeming this coupon. Users who have less points then this value will not be able to redeem this coupon.
`min_balance_type`	string	No	Optional point type key for the minimum balance requirement.
`max_balance`	INT or FLOAT	No	Optional maximum balance requirement for redeeming this coupon. Users who have more points then this value will not be able to redeem this coupon.
`max_balance_type`	string	No	Optional point type key for the maximum balance requirement.
`expires`	INT	No	Optional expiration date for the coupon. Uses strtotime to convert the date into a UNIX timestamp. Do not use if the coupon never expires / expires when used up.

Examples

Example 1: Create a new coupon that can be used 10 times in total and gives 5 points when redeemed.

				
					$args = array(
	'value'      => 5,
	'global_max' => 10
);
$new_coupon = mycred_create_new_coupon( $args );

if ( $new_coupon !== false && ! is_wp_error( $new_coupon ) ) {

	// Coupon was successfully created

}

Example 2: Create a new coupon called “XMASOFFER“ that gives 100 points when redeemed. In order to use the coupon, the user must have less than 100 points. Make sure the coupon can not be used more than 500 times.

				
					$args = array(
	'code'        => 'XMASOFFER'
	'value'       => 100,
	'global_max'  => 500,
	'max_balance' => 100
);
$new_coupon = mycred_create_new_coupon( $args );

if ( $new_coupon !== false && ! is_wp_error( $new_coupon ) ) {

	// Coupon was successfully created

}

mycred_date_to_gmt_timestamp

Package: mycred/core Category: Functions

Description

This function will convert a well formatted date to a GMT unix timestamp. Uses strtotime.

Available since version 1.7

Returns

(int | bool) Returns a UNIX timestamp or FALSE if the date provided if incorrectly formatted.

Parameters

	Param	Type	Required	Description
function `mycred_date_to_gmt_timestamp(`
	`$date`	STRING	Yes	A well formatted date that strtotime understands.
`) { ... }`

Example

Example 1: Convert a given date into a GMT unix timestamp

				
					$date = '2016-12-01';

$timestamp = mycred_date_to_gmt_timestamp( $date );

mycred_delete_recurring_payout

Package: mycred/banking Category: Functions

Description

Deletes a given recurring payout in the Banking add-on.

This function is only available if the Banking add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the schedule was deleted else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_delete_recurring_payout(`
	`$id`	STRING	Yes	The recurring payout ID.
	`$point_type`	STRING	No	Optional point type key if we are not deleting a recurring payout for the default point type.
`) { ... }`

Example

Example 1: Delete the recurring payout with the ID 1.

				
					$payout = 1;

mycred_delete_recurring_payout( $payout );

mycred_delete_user_meta

Package: mycred/core Category: Functions

Description

A wrapper function for delete_user_meta, it assures that point related data is deleted under the correct meta key structure.

Available since version 1.5

Returns

(bool) TRUE if user meta was deleted else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_delete_user_meta(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$meta_key`	STRING	Yes	The meta key id.
	`$end`	STRING	No	Optional ending to append to the meta key id. In certain situation on Multisites, the meta key gets the blogs ID appended. The value of `$end` is then appended after the blog ID, whilst the value of `$meta_key` is before the blog id. On regular WordPress installations `$end` is appended onto `$meta_key`.
	`$value`	STRING	No	The meta value. Should be left empty unless the meta data being deleted is not unique.
`) { ... }`

mycred_display_badge_requirements

Package: mycred/badge Category: Functions

Description

This function will return the requirements you set for a particular badge in readable format.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

(string) Returns an unorganized list.

Parameters

	Param	Type	Required	Description
function `mycred_display_badge_requirements(`
	`$badge_id`	INT	Yes	The badge post object ID.
`) { ... }`

Example

Example 1: Display the requirements for a badge.

				
					$badge_id = 1;

echo mycred_display_badge_requirements( $badge_id );

mycred_display_users_badges

Package: mycred/badge Category: Functions

Description

This function renders a list of all the badges a give user has earned.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

All badge images a user has earned.

Parameters

	Param	Type	Required	Description
function `mycred_display_users_badges(`
	`$user_id`	INT	Yes	The users numeric ID.
`) { ... }`

Example

Example 1: Show the current users badges.

				
					$user_id = get_current_user_id();

echo '<h3>Your badges</h3>';
mycred_display_users_badges( $user_id );

mycred_display_users_balance

Package: mycred/balance Category: Functions

Description

Returns a given users current balance for a specific point type formatted. This means the balance will be applied the appropriate separator characters you have defined along with any prefix / suffix that might be set. If you are looking to display a user’s total balance, consider using the mycred_display_users_total_balance function instead.

If you are using version 1.7.3 or older, you must use the mycred_get_users_fcred function name instead of this one. Both work exactly the same.

Available since version 1.7.4

Returns

(string | bool) The users current balance formatted with prefix / suffix (if used). If the user ID is invalid or the user is excluded, this function will return FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_display_users_balance(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key. Should only be used if you require the balance of a custom point type.
`) { ... }`

Example

Example 1: Show the current users balance.

				
					$user_id = get_current_user_id();
echo mycred_display_users_balance( $user_id );

Example 2: Get the BuddyPress profiles custom point type current balance.

				
					$profile_id = bp_displayed_user_id();
echo mycred_display_users_balance( $profile_id, 'customtypekey' );

mycred_display_users_total_balance

Package: mycred/balance Category: Functions

Description

Returns a given users total balance for a specific point type formatted. This means the balance will be applied the appropriate separator characters you have defined along with any prefix / suffix that might be set. If you are looking to display a user’s current balance, consider using the mycred_display_users_balance function instead.

Available since version 1.7.6

Returns

(string | bool) The users total balance formatted with prefix / suffix (if used). If the user ID is invalid or the user is excluded, this function will return FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_display_users_total_balance(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key. Should only be used if you require the balance of a custom point type.
`) { ... }`

Examples

Example 1: Get the current users total balance.

				
					$user_id = get_current_user_id();
echo mycred_display_users_total_balance( $user_id );

Example 2: Get the BuddyPress profiles custom point type total balance.

				
					$profile_id = bp_displayed_user_id();
echo mycred_display_users_total_balance( $profile_id, 'customtypekey' );

mycred_exclude_user

Package: mycred/core Category: Functions

Description

Checks if a given user is excluded from using a particular point type.

Available since version 1.0

Returns

(bool) TRUE if the user is excluded else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_exclude_user(`
	`$user_id`	INT	Yes	The numeric ID of the user.
	`$point_type`	STRING	No	The point type to check for.
`) { ... }`

Example

Example 1: Check if the current user is excluded from the default point type.

				
					$user_id = get_current_user_id();

if ( mycred_exclude_user( $user_id ) ) {

	// User is excluded

}

mycred_find_users_rank

Package: mycred/rank Category: Functions

Description

This function will attempt to find a given users rank of a specific point type. This function can be used to just query which rank a user should have or also save this rank.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(object | bool) Returns either FALSE if no rank was found or an object containing the users current rank, the rank they should have and the ranks requirements.

Object example:

				
					Std Object
(
    [rank_id] => 1	// The rank post object ID a user should have
    [minimum] => 0	// The ranks minimum point requirement
    [maximum] => 999	// The ranks maximum point requirement
    [current_id] => 1	// The rank post object ID the user currently has assigned
)

Parameters

	Param	Type	Required	Description
function `mycred_find_users_rank(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key.
	`$act`	BOOL	No	`TRUE` if the rank should be saved or `FALSE` if not. Defaults to `TRUE`.
`) { ... }`

Example

Example 1: Check what rank a user should have without saving the results.

				
					$user_id = get_current_user_id();
$rank    = mycred_find_users_rank( $user_id, 'mycred_default', false );

if ( $rank === false && $rank->rank_id !== $rank->current_id ) {

	// The user should have a new rank

}

mycred_flush_widget_cache

Package: mycred/core Category: Functions

Description

Wrapper function for wp_cache_delete for deleting widget caches. Used when myCRED widget settings are saved.

Available since version 1.0

Returns

void

Parameters

	Param	Type	Required	Description
function `mycred_flush_widget_cache(`
	`$id`	STRING	Yes	The widget ID to flush.
`) { ... }`

Example

Example 1: Flush the cache for a widget with the ID “mycred_widget“.

				
					mycred_flush_widget_cache( 'mycred_widget' );

mycred_force_singular_session

Package: mycred/core Category: Functions

Description

This function is used throughout myCRED to prevent users from attempting to submit AJAX forms multiple times. The minimum time that has to pass between AJAX calls is controlled by the MYCRED_MIN_TIME_LIMIT constant.

Available since version 1.7

Returns

(bool) TRUE if an AJAX call was made within the timelimit else FALSE. A task should be terminated if this function returns TRUE.

Parameters

	Param	Type	Required	Description
function `mycred_force_singular_session(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$key`	STRING	Yes	A unique meta key that identifies the current transaction.
	`$timelimit`	INT	No	The number of seconds that has to pass between AJAX calls. Defaults to the value of the MYCRED_MIN_TIME_LIMIT constant.
`) { ... }`

mycred_get_account

Package: mycred/core Category: Functions

Description

Retrives the myCRED_Account object for a given user.

Available since version 1.8

Returns

(bool | object) Returns either FALSE or the myCRED_Account object for the given user.

Parameters

	Param	Type	Required	Description
function `mycred_get_account(`
	`$user_id`	INT	No	The users numeric ID. If no ID is provided and the function is used after the WordPress `init` instance has run, the current users ID is used instead. Will return false if the user ID is invalid or if the current user is not logged in.
`) { ... }`

Example

Example 1: Get the account object for the user with the ID 3.

				
					$user_id = 3;
$account = mycred_get_account( $user_id );
if ( $account !== false ) {

	// Object exists

}

mycred_get_badge

Package: mycred/badge Category: Functions

Description

This function returns the myCRED Badge Object for a given badge ID.

This function is only available if the Badges add-on is enabled.

Returns

(bool | object) Returns either the Badge object or FALSE if the ID is invalid or does not belong to a badge post type.

Parameters

	Param	Type	Required	Description
function `mycred_get_badge(`
	`$badge_id`	INT	Yes	The badge post object ID.
	`$level`	INT	No	Option to construct the object around a particular badge level. This in turn pre-loads level related details like the level image.
`) { ... }`

Example

Example 1: Display a given badges main image.

				
					$badge_id = 1;
$badge    = mycred_get_badge( $badge_id );

echo $badge->main_image;

mycred_get_badge_ids

Package: mycred/badge Category: Functions

Description

This function returns an array of published badge IDs.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

(array) Array of post object IDs.

Parameters

	Param	Type	Required	Description
function `mycred_get_badge_ids(`
No params
`) { ... }`

Example

Example 1: Count the number of published badges that exists on our website.

				
					$badge_ids = mycred_get_badge_ids();

printf( 'This website has %d badges you can earn.', count( $badge_ids ) );

mycred_get_badge_references

Package: mycred/badge Category: Functions

Description

This function will return an associative array of references and badge IDs that exists on your website. This function is mainly used for quick checks if a particular reference has badges associated with it.

This function is only available if the Badges add-on is enabled.

Available since version 1.7

Returns

(array) Associative array of references and the badge post object IDs belonging to each reference.

Parameters

	Param	Type	Required	Description
function `mycred_get_badge_references(`
	`$point_type`	STRING	No	Option to query badges for a particular point type. Defaults to the main point type.
	`$force`	BOOL	No	By default, badge references are cached to minimize database queries. This cache is reset each time you save a badge but you can use this parameter to force a new query, which in turn will reset the current cached results.
`) { ... }`

Example

Example 1: Check if the reference “approved_comment“ exists among published badges.

				
					$reference  = 'approved_comment';
$badge_refs = mycred_get_badge_references();

if ( ! empty( $badge_refs ) && array_key_exists( $reference, $badge_refs ) ) {

	// Values are always an array since a reference might exists
	// in more than one badge
	$badge_ids = $badge_refs[ $reference ];

}

mycred_get_content_buyers_count

Package: mycred/content Category: Functions

Description

This function returns the total number of unique users that have purchased a given post.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(int) The total number of users that has bought this post.

Parameters

	Param	Type	Required	Description
function `mycred_get_content_buyers_count(`
	`$post_id`	INT	Yes	The post object ID.
`) { ... }`

Example

Example 1: Get the current posts total buyers count.

				
					global $post;

printf( 'A total of %d users have bought access to this post!', mycred_get_content_buyers_count( $post->ID ) );

mycred_get_content_price

Package: mycred/content Category: Functions

Description

This function returns the set price for a post that has been set for sale using the Sell Content add-on.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(int | float) Returns the price set for the given point type.

Parameters

	Param	Type	Required	Description
function `mycred_get_content_price(`
	`$post_id`	INT	Yes	The post object ID.
	`$point_type`	STRING	No	Option to get a price of a specific point type. Should only be used if posts are set for sale using a custom point type.
`) { ... }`

Example

Example 1: Get the current posts price

				
					global $post;

if ( mycred_post_is_for_sale( $post ) )
	printf( 'This post costs %s points', mycred_get_content_price( $post->ID ) );

mycred_get_content_sales_count

Package: mycred/content Category: Functions

Description

This function returns the total number of times a particular posts content has been purchased.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(int) The total number of logged transactions.

Parameters

	Param	Type	Required	Description
function `mycred_get_content_sales_count(`
	`$post_id`	INT	Yes	The post object ID.
`) { ... }`

Example

Example 1: Get the current posts total buyers count.

				
					global $post;

printf( 'This post has been purchased %d times.', mycred_get_content_sales_count( $post->ID ) );

mycred_get_coupon

Package: mycred/coupon Category: Functions

Description

This function returns a coupon object based on a coupon post ID.

This function is only available if the Coupons add-on is enabled.

Available since version 1.7

Returns

(bool | object) Returns the coupon object or FALSE if the coupon post ID is invalid.

Coupon Object Example

				
					Std Object
(
    [post_id] => 1
    [code] => 'ABC123'
    [value] => 10.00
    [point_type] => 'mycred_default'
    [max_global] => 100
    [max_user] => 1
    [requires_min] => 0
    [requires_min_type] => 'mycred_default'
    [requires_max] => 0
    [requires_max_type] => 'mycred_default'
    [used] => 0
    [expires] => false
    [expires_unix] => false
)

Parameters

	Param	Type	Required	Description
function `mycred_get_coupon(`
	`$coupon_post_id`	INT	Yes	The coupon post object ID.
`) { ... }`

Example

Example 1: Get a coupons point value.

				
					$coupon_id = 1;
$coupon    = mycred_get_coupon( $coupon_id );

printf( 'This coupon gives %d points.', $coupon->value );

mycred_get_email_notice

Package: mycred/email Category: Functions

Description

Returns an instance of the myCRED_Email object based on a given email notice post ID.

This function is only available if the Email Notifications add-on is enabled.

Available since version 1.8

Returns

(bool | obj) Returns FALSE if an invalid email ID is provided else the myCRED_Email object.

Parameters

	Param	Type	Required	Description
function `mycred_get_email_notice(`
	`$notice_id`	INT	Yes	The email notifications post ID.
`) { ... }`

Example

Example 1: Get an instance for the email notice ID 123

				
					$notice_id = 123;
$email     = mycred_get_email_notice( $notice_id );
if ( $email !== false ) {

	// do something

}

mycred_get_global_coupon_count

Package: mycred/coupon Category: Functions

Description

This function returns the total number of times a given coupon has been redeemed on your website.

This function is only available if the Coupons add-on is enabled.

Available since version 1.4

Returns

(int) The total number of times the coupon has been used.

Parameters

	Param	Type	Required	Description
function `mycred_get_global_coupon_count(`
	`$coupon_post_id`	INT	Yes	The coupon post object ID.
`) { ... }`

Example

Example 1: Count the number of times a coupon has been used.

				
					$coupon_id = 1;
$count     = mycred_get_global_coupon_count( $coupon_id );

printf( 'The coupon %s has been used %d times.', get_the_title( $coupon_id ), $count );

mycred_get_module

Package: mycred/core Category: Functions

Description

This function will return a specific myCRED Module object.

Available since version 1.7.3

Returns

(bool | object) Returns the module object or FALSE if the module is not found.

Parameters

	Param	Type	Required	Description
function `mycred_get_module(`
	`$module`	STRING	Yes	The module ID.
	`$type`	STRING	Yes	If the module supports multiple point types, you can use this to get the module under a specific point type. If the module however only supports one type, the correct value would be `solo`.
`) { ... }`

mycred_get_my_rank

Package: mycred/rank Category: Functions

Description

This function returns the current users myCRED rank object. Uses the mycred_get_users_rank function.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(object) Returns the current users rank object. If the user is not logged in, the function returns NULL.

Parameters

	Param	Type	Required	Description
function `mycred_get_my_rank(`
No params
`) { ... }`

Example

Example 1: Show the current users rank.

				
					if ( is_user_logged_in() ) {

	$rank = mycred_get_my_rank();
	if ( isset( $rank->post_id ) ) {
		printf( 'Your current rank is: %s', $rank->title );
	}
	else {
		echo 'You do not have a rank yet.';
	}

}

mycred_get_point_type_name

Package: mycred/core Category: Functions

Description

This function returns a specific point type’s given name in singular or plural form.

Available since version 1.0

Returns

(string) The point types name.

Parameters

	Param	Type	Required	Description
function `mycred_get_point_type_name(`
	`$point_type`	STRING	No	The point type key. Defaults to the default point type.
	`$singular`	BOOL	No	`TRUE` for singular form else `FALSE`.
`) { ... }`

mycred_get_rank

Package: mycred/rank Category: Functions

Description

This function will return the myCRED Rank Object for a given rank ID. Uses the mycred_get_rank_object_id function to convert rank names to rank IDs.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(bool | object) FALSE if the provided rank ID is invalid or the myCRED_Rank object.

Parameters

	Param	Type	Required	Description
function `mycred_get_rank(`
	`$rank_identifier`	–	Yes	Either the rank post object ID or the ranks name (case sensitive).
`) { ... }`

Example

Example 1: Get the rank object for the rank called “Master“.

				
					$rank_id = 'Master';
$rank    = mycred_get_rank( $rank_id );

mycred_get_rank_logo

Package: mycred/rank Category: Functions

Description

This function will return a given ranks logo image. Note that this function will return an image HTML element if the rank is found.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(bool | string) FALSE if the rank ID is invalid or if the logo is not set else the logo HTML image element.

Parameters

	Param	Type	Required	Description
function `mycred_get_rank_logo(`
	`$rank_identifier`	INT or STRING	Yes	Either the rank post object ID or the rank name (case sensitive).
	`$size`	STRING or ARRAY	No	The image size. See the get_the_post_thumbnail function for possible values.
	`$attr`	ARRAY	No	Optional image attributes to pass on to get_the_post_thumbnail function.
`) { ... }`

Example

Example 1: Get a ranks logo in thumbnail size (default).

				
					$rank_id   = 1;
$rank_logo = mycred_get_rank_logo( $rank_id );

echo $rank_logo;

Example 2: Get a ranks logo in full size.

				
					$rank_id   = 'Master';
$rank_logo = mycred_get_rank_logo( $rank_id, 'full' );

echo $rank_logo;

mycred_get_rank_object_id

Package: mycred/rank Category: Functions

Description

This function attempts to convert a given rank name into it’s post object ID. If a post ID is provided, this ID is returned instead. When providing a rank name, make sure the name is exact as names are case sensitive. Supports the Multisite Master Template feature.

This function is only available if the Ranks add-on is enabled.

Available since version 1.7

Returns

(int | bool) The rank post object ID else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_get_rank_object_id(`
	`$identifier`	INT or STRING	Yes	Either a rank post object ID or a rank Name
`) { ... }`

Example

Example 1: Get the rank post ID for the rank “Beginner“.

				
					$rank_name = 'Beginner';
$rank_id   = mycred_get_rank_object_id( $rank_name );

mycred_get_ranks

Package: mycred/rank Category: Functions

Description

This function allows you to query existing ranks for a specific point type.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(array) Returns an associative array of rank objects or an empty array if no ranks were found.

Parameters

	Param	Type	Required	Description
function `mycred_get_ranks(`
	`$status`	STRING	Yes	Rank post object status to query. Defaults to `publish` for published ranks.
	`$number`	INT	Yes	Number of ranks to get. Use `-1` to return all. Defaults to `-1`.
	`$order`	STRING	No	Sorting order of ranks. Accepts `ASC` for ascending or `DESC` for descending order. Defaults to `DESC`.
	`$point_type`	STRING	No	Option to return ranks only for a particular point type. By default, this function will return all ranks no matter which point type they belong to. Should only be used if you need to get ranks of a custom point type.
`) { ... }`

Example

Example 1: Get all published ranks.

				
					$ranks = mycred_get_ranks();

Example 2: Get all published ranks for a custom point type

				
					$ranks = mycred_get_ranks( 'publish', -1, 'DESC', 'customtypekey' );

Example 3: Get the 5 lowest ranks.

				
					$ranks = mycred_get_ranks( 'publish', 5, 'ASC' );

mycred_get_recurring_payout

Package: mycred/banking Category: Functions

Description

This function returns the settings and status of a given scheduled recurring payout in the Banking add-on.

This function is only available if the Banking add-on is enabled.

Available since version 1.7

Returns

(array) Returns the setup and status array.

Schedule Setup Example

				
					Array
(
    [job_title]       => '',
    [status]          => 0,
    [payout]          => '',
    [frequency]       => 'daily',
    [last_run]        => '',
    [total_runs]      => 1,
    [runs_remaining]  => 0,
    [min_balance]     => 0,
    [max_balance]     => 0,
    [id_exclude]      => 'exclude',
    [id_list]         => '',
    [role_exclude]    => 'exclude',
    [role_list]       => array(),
    [log_template]    => '%plural% payout',
    [total_completed] => 0,
    [total_misses]    => 0,
    [ignore_central]  => 0
)

Parameters

	Param	Type	Required	Description
function `mycred_get_recurring_payout(`
	`$schedule_id`	STRING	Yes	The recurring payout schedule ID.
	`$point_type`	STRING	No	The point type key the schedule belongs to. Defaults to the default point type.
`) { ... }`

Example

Example 1: Show the total completed runs a given schedule has made so far.

				
					$schedule_id      = 'abc124';
$recurring_payout = mycred_get_recurring_payout( $schedule_id );

printf( 'A total of %d recurring payouts have run so far.', $recurring_payout['total_completed'] );

mycred_get_recurring_payout_schedules

Package: mycred/banking Category: Functions

Description

This function will return all currently existing recurring payout schedules in the Banking add-on.

This function is only available if the Banking add-on is enabled.

Available since version 1.7

Returns

(array) Returns an associative array of schedule IDs and the associated setup for each schedule.

Parameters

	Param	Type	Required	Description
function `mycred_get_recurring_payout_schedules(`
	`$point_type`	STRING	No	The point type key to return schedules for. Defaults to the default point type.
`) { ... }`

Example

Example 1: Count the total number of recurring schedules currently in use on our website.

				
					$schedules = mycred_get_recurring_payout_schedules();

printf( 'There are %d recurring payouts currently running on this website', count( $schedule ) );

mycred_get_remote

Package: mycred/core Category: Functions

Description

This function returns the Remove API (version 1.0) settings.

Available since version 1.3

Returns

(array) Associative array.

Settings example:

				
					Array
(
    [enabled] => 0
    [key]     => 'abc123'
    [uri]     => 'api-dev'
    [debug]   => 0
)

Parameters

	Param	Type	Required	Description
function `mycred_get_remote(`
No params
`) { ... }`

mycred_get_settings_network

Package: mycred/core Category: Functions

Description

This function returns the network settings on a Multisite installation.

Available since version 1.0

Returns

(array | bool) Returns either the network settings array or FALSE if mulsite is not being used.

Network Settings Example

				
					Array
(
    [master]  => 0
    [central] => 0
    [block]   => ''
)

Parameters

	Param	Type	Required	Description
function `mycred_get_settings_network(`
No params
`) { ... }`

mycred_get_total_by_time

Package: mycred/log Category: Functions

Description

This function will return the total number of points logged in the log table between two dates, either in total, for a specific reference or for a specific user.

Available since version 1.1.1

Returns

(int | float) The total amount of points resulting from this query.

Parameters

	Param	Type	Required	Description
function `mycred_get_total_by_time(`
	`$from`	INT or STRING	No	A timestamp or keyword that indicates from what date/time we should start counting. Uses strtotime to convert a start date/time into a UNIX timestamp. Defaults to the keyword `today`.
	`$until`	INT or STRING	No	A timestamp or keyword that indicates the date/time where counting should end. Uses strtotime to convert a end date/time into a UNIX timestamp. Defaults to the keyword `now`.
	`$reference`	STRING	No	Option to filter the query to sum up only entries of a particular reference.
	`$user_id`	INT	No	Option to filter the query to sum up only entries of a particular user.
	`$point_type`	STRING	No	Option to filter the query to sum up only entries of a particular point type. Defaults to the default point type.
`) { ... }`

Examples

Example 1: Get the total amount of points that users have gained/lost from start of today until now

				
					$total = mycred_get_total_by_time();

printf( 'A total of %d points have been gained today.', $total );

Example 2: Get the total amount of points that users have gained/lost from January 1st until November 30th.

				
					$total = mycred_get_total_by_time( '2016-01-01', '2016-11-30' );

echo $total . ' points';

Example 3: Get the total amount of points that has been spent on WooCommerce order payments the last 7 days.

				
					$total = mycred_get_total_by_time( '-1 week', 'now', 'woocommerce_payment' );

printf( 'A total of %d points have been spent in the store in the past 7 days', abs( $total ) );

mycred_get_transfer

Package: mycred/transfer Category: Functions

Description

This function retrieves the myCRED_Transfer object, populated based on the given transfer ID. This function can only be used for transfers that have been processed.

This function is only available if the Transfer add-on is enabled.

Available since version 1.8

Returns

(bool | object) Either the myCRED_Transfer object or FALSE if the transfer was not found.

Parameters

	Param	Type	Required	Description
function `mycred_get_transfer(`
	`$transfer_id`	STRING	Yes	The transfer ID.
`) { ... }`

Example

Example 1: Get the transfer object for a transfer ID.

				
					$transfer_id = 'TXT384723943843';
if ( function_exists( 'mycred_get_transfer' ) ) {

	$transfer = mycred_get_transfer( $transfer_id );
	if ( $transfer !== false ) {

		// found transfer

	}

}

mycred_get_unique_coupon_code

Package: mycred/coupon Category: Functions

Description

This function will generate a unique random code for coupons. The generated value is ensured to be unique.

This function is only available if the Coupons add-on is enabled.

Available since version 1.4

Returns

(string) Random coupon code, 12 characters long.

Parameters

	Param	Type	Required	Description
function `mycred_get_unique_coupon_code(`
No params
`) { ... }`

Example

Example 1: Generate a unique coupon code.

				
					$code       = mycred_get_unique_coupon_code();
$args       = array(
	'code'       => $code,
	'global_max' => 100,
	'value'      => 10,
	'expires'    => '2020-01-01'
);
$new_coupon = mycred_create_new_coupon( $args );

mycred_get_user_id

Package: mycred/core Category: Functions

Description

This function will attempt to return a user ID based on either an identifying piece of information (email, login or slug) or based on keywords.

Available since version 1.7

Returns

(int | string) Returns either the users ID or the parameter passed to this function if nothing was found.

Parameters

	Param	Type	Required	Description
function `mycred_get_user_id(`
	`$identifier`	INT or STRING	Yes	Either a keyword or a piece of information that can be used to get a user from the database.
`) { ... }`

Keywords

An empty $identifier parameter will return the current users ID.

Keyword	Description
`current`	Retrieves the current users ID. This will be zero if the user is not logged in.
`author`	Returns the current posts author ID. Can only be used inside the loop.
`replyauthor`	Returns the bbPress topic reply authors ID. Can only be used inside a bbPress loop.
`bbprofile`	Returns the displayed profiles ID. Can only be used in BuddyPress profile pages.

mycred_get_users_badges

Package: mycred/badge Category: Functions

Description

This function returns an array badge IDs that a given user has earned.

This function is only available if the Badges add-on is enabled.

Available since version 1.5

Returns

(string | array) Returns either an array of post IDs or an empty string if the user ID provided is invalid.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_badges(`
	`$user_id`	INT	Yes	The users numeric ID.
`) { ... }`

Example

Example 1: Count the number of badges the current user has earned

				
					$user_id   = get_current_user_id();
$badge_ids = mycred_get_users_badges( $user_id );

$badge_count = 0;
if ( ! empty( $badge_ids ) )
	$badge_count = count( $badge_ids );

mycred_get_users_balance

Package: mycred/balance Category: Functions

Description

This function returns a given user’s current point balance for a specific point type. If you are looking to get a users total balance, consider using the mycred_get_users_total_balance function instead.

If you are using version 1.7.3 or older, you must use the mycred_get_users_cred function name instead of this one. Both work exactly the same.

Available since version 1.7.4

Returns

(int | float | bool) Returns a users balance without any prefix or suffix formatting. If the user ID is invalid or the user is excluded, the function will return FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_balance(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key. Should only be used if you require the balance of a custom point type.
`) { ... }`

Examples

Example 1: Get the current users balance.

				
					$user_id = get_current_user_id();
$balance = mycred_get_users_balance( $user_id );

Example 2: Get the BuddyPress profiles custom point type balance.

				
					$profile_id = bp_displayed_user_id();
$balance    = mycred_get_users_balance( $profile_id, 'customtypekey' );

mycred_get_users_coupon_count

Package: mycred/coupon Category: Functions

Description

This function returns the total number of times a user has redeemed a specific coupon.

This function is only available if the Coupons add-on is enabled.

Available since version 1.4

Returns

(int) The number of times the coupon has been used.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_coupon_count(`
	`$code`	STRING	Yes	The coupon code. Note that this function checks the code and not the post ID.
	`$user_id`	INT	Yes	The users numeric ID.
`) { ... }`

Example

Example 1: Check the number of times a user has used our holiday coupon.

				
					$coupon_code = 'XMASOFFER';
$user_id     = get_current_user_id();
$count       = mycred_get_users_coupon_count( $coupon_code, $user_id );

printf( 'You have used this coupon %d times', $count );

mycred_get_users_of_rank

Package: mycred/rank Category: Functions

Description

This function allows you to query users of a specific rank. Users will be sorted based on their balance.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(array) Returns an array of objects with users ID and their current balance or an empty array if no users were found.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_of_rank(`
	`$rank_identifier`	INT or STRING	Yes	Either the rank post object ID or the ranks name (case sensitive).
	`$number`	INT	Yes	The number of users to return. Use `-1` to return all users. Defaults to `-1`.
	`$order`	STRING	No	The sorting order. Accepts `ASC` for ascending or `DESC` for descending order. Defaults to `DESC`.
	`$point_type`	STRING	No	Point type key. Should only be used if you want to show users with a rank of a custom point type.
`) { ... }`

Example

Example 1: Get the top 10 users with the rank “Master“.

				
					$users = mycred_get_users_of_rank( 'Master', 10 );

mycred_get_users_profile_url

Package: mycred/core Category: Functions

Description

This function will return a given users profile URL based on your websites setup. If you have BuddyPress or bbPress installed, the function will return the profile URL these plugins provide. Supports setups where the author_base has been changed.

Available since version 1.7.4

Returns

Returns the profile url string of the given user or an empty string if the user ID is blank or zero.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_profile_url(`
	`$user_id`	INT	Yes	The numeric user ID.
`) { ... }`

Example

Example 1: Echo the current users profile URL.

				
					if ( function_exists( 'mycred_get_users_profile_url' ) ) {

	$user_id     = get_current_user_id();
	$profile_url = mycred_get_users_profile_url( $user_id );

	echo '<a href="' . esc_url( $profile_url ) . '">View Profile</a>';

}

mycred_get_users_rank

Package: mycred/rank Category: Functions

Description

This function will retrieve a given users current rank object for a specific point type. If you only need the rank post object ID, consider instead using the mycred_get_users_rank_id function instead.

This function is only available if the Ranks add-on is enabled.

This function was completely re-written in version 1.7! This documentation is incorrect for older versions of myCRED.

Available since version 1.1

Returns

(object | string) Returns either the rank object or an empty string if the user does not have a rank.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_rank(`
	`$user_id`	INT	Yes	The numeric ID of the user.
	`$point_type`	STRING	No	The point type key to return a rank for. Should only be used when you have ranks setup for more than one point type.
`) { ... }`

Example

Example 1: Get a users rank object.

				
					$user_id = 1;

// Always make sure the function exists to prevent crashes
// If the ranks add-on gets disabled or myCRED gets disabled
// this function will no longer exist!
if ( function_exists( 'mycred_get_users_rank' ) ) {

	// Get rank object
	$rank = mycred_get_users_rank( $user_id );
	
	// If the user has a rank, $rank will be an object
	if ( is_object( $rank ) ) {
	
		// Show rank title
		echo $rank->title;
	
		// Show rank logo (if one exists)
		if ( $rank->has_logo )
			echo $rank->get_image( 'logo' );
	
		// Show total number of users with this rank
		echo $rank->count;
	
	}

}

mycred_get_users_rank_id

Package: mycred/rank Category: Functions

Description

This function returns a given users current rank post object ID of a specific point type. If you are looking to get the users rank object, consider using mycred_get_users_rank instead.

This function is only available if the Ranks add-on is enabled. .

Available since version 1.6

Returns

(string | int) Returns either the rank post object ID or an empty string if no rank is found.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_rank_id(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key to return a rank for. Should only be used when you have ranks setup for more than one point type.
`) { ... }`

Example

Example 1: Get the current users rank and display the ranks title.

				
					$user_id = get_current_user_id();
$rank_id = mycred_get_users_rank_id( $user_id );

if ( $rank_id != '' )
	printf( 'Your current rank is: %s', get_the_title( $rank_id ) );
else
	echo 'You do not have a rank yet';

mycred_get_users_reference_sum

Package: mycred/log Category: Functions

Description

This function will return an array of all point instances a user has based on the log. The array will include the reference and the amount of points that have been gained / spent for that reference.

The results this function returns are cached. This cache is flushed each time a user gained / loses points. .

Available since version 1.7

Returns

(array) Associative array of references and points.

Results example where a user has a history of getting points for comments, publishing content and has spent points in a WooCommerce store

				
					Array
(
    [approved_comment]    => 25
    [publishing_content]  => 150
    [woocommerce_payment] => -3200
)

Parameters

	Param	Type	Required	Description
function `mycred_get_users_reference_sum(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type to query. Note that a point type must be set in order to use this function. You can not query points for all point types with this function. Defaults to the default point type.
`) { ... }`

Example

Example 1: Check if the current user has gained myCRED points for publishing content, and if they have gained more than 1000 points and are not yet authors, promote them to the Author role.

				
					$user_id  = get_current_user_id();
$ref_sums = mycred_get_users_reference_sum( $user_id );

// Check if user has gained points for published content
if ( ! empty( $ref_sums ) && array_key_exists( 'publishing_content', $ref_sums ) ) {

	// If they have, check if it's over 1000 points and that they are not yet "Authors"
	if ( $ref_sums['publishing_content'] >= 1000 && ! user_can( $user_id, 'publish_posts' ) )
		wp_update_user( array(
			'ID'   => $user_id,
			'role' => 'author'
		) );

}

mycred_get_users_total_balance

Package: mycred/balance Category: Functions

Description

This function returns a given user’s total point balance for a specific point type. If you are looking to get a users current balance, consider using the mycred_get_users_balance function instead.

Available since version 1.7.6

Returns

(int | float | bool) Returns a users balance without any prefix or suffix formatting. If the user ID is invalid or the user is excluded, the function will return FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_get_users_total_balance(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	No	The point type key. Should only be used if you require the balance of a custom point type.
`) { ... }`

Examples

Example 1: Get the current users total balance.

				
					$user_id = get_current_user_id();
$balance = mycred_get_users_total_balance( $user_id );

Example 2: Get the BuddyPress profiles custom point type total balance.

				
					$profile_id = bp_displayed_user_id();
$balance    = mycred_get_users_total_balance( $profile_id, 'customtypekey' );

mycred_get_woo_product_reward

Package: mycred/payment Category: Functions

Description

This function will retrieve the amount of points a WooCommerce product is set to reward when purchased, or an array of point types with their associated values if more than one point type exists. Supports both single or variable product types.

This function is only available if myCRED and WooCommerce is installed and enabled on your site!

Available since version 1.7.6

Returns

(bool) FALSE if the product ID is invalid, an array of the reward setup for all point types or the point value in string form when used to retrieve a particular point type.

Parameters

	Param	Type	Required	Description
function `mycred_get_woo_product_reward(`
	`$product_id`	INT	Yes	The WooCommerce product post object ID.
	`$variation_id`	INT	No	Should be set to `NULL` if the product is not a variable product, otherwise the variations numeric ID.
	`$requested_type`	BOOL or STRING	No	Use `FALSE` to retrieve values for multiple point types in a associative array format or provide the point type key to retrieve the value for a particular type.
`) { ... }`

Example

Example 1: Basic usage example where we show how much points a product rewards (if set).

				
					if ( function_exists( 'mycred_get_woo_product_reward' ) ) {

	$product_id = 1;
	$point_type = MYCRED_DEFAULT_TYPE_KEY;
	$reward     = mycred_get_woo_product_reward( $product_id, NULL, $point_type );

	if ( $reward !== false && $reward != '' )
		printf( 'Earn %s Points buying this product.', $reward );

}

mycred_have_ranks

Package: mycred/rank Category: Functions

Description

This function checks if there are published rank post objects for a particular point type.

This function is only available if the Ranks add-on is enabled.

Available since version 1.1

Returns

(bool) TRUE if there are published ranks else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_have_ranks(`
	`$point_type`	STRING	No	The point type key to check ranks for. Defaults to the default point type.
`) { ... }`

mycred_is_admin

Package: mycred/core Category: Functions

Description

This function checks if a specific user is to be considered an “administrator”. Administrators are users that have one of the capabilities you have set for “Point Editors” or “Point Administrators”.

Available since version 1.0

Returns

(bool) TRUE if the user is an administrator else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_is_admin(`
	`$user_id`	INT	No	The users numeric ID. If no ID is provided, the current user will be checked.
	`$point_type`	STRING	No	The point type key. Should only be used if you are checking for a custom point type.
`) { ... }`

Example

Example 1: Check if the current user is an administrator.

				
					if ( mycred_is_admin() ) {

	// User is an admin

}

mycred_label

Package: mycred/core Category: Functions

Description

This function returns the myCRED label as defined either via the mycred_label filter or by the MYCRED_DEFAULT_LABEL constant.

Available since version 1.3.3

Returns

(string) The plugin name.

Parameters

	Param	Type	Required	Description
function `mycred_label(`
	`$trim`	BOOL	No	`TRUE` to strip HTML tags of the name (if used) else `FALSE`.
`) { ... }`

mycred_new_transfer

Package: mycred/transfer Category: Functions

Description

This function attempts to process a transfer request that has been submitted by a transfer form. If no transfer form is used and you need to process a new transfer artificially, make sure you simulate a form submission by providing an array of form names and values.

This function is only available if the Transfer add-on is enabled.

Available since version 1.7.6

Returns

(bool | string | array) Returns either an error code if the request could not be processed, FALSE if the request was valid but the transaction could not be completed else an array of transfer results.

Parameters

	Param	Type	Required	Description
function `mycred_new_transfer(`
	`$request`	ARRAY	Yes	The transfer request array.
	`$posted`	ARRAY	Yes	An array of the transfer form that was submitted.
`) { ... }`

mycred_override_settings

Package: mycred/core Category: Functions

Description

This function checks if the master template feature is enabled on a Multisite installation. Will return FALSE if Multisite are not being used.

Available since version 1.0

Returns

(bool) TRUE if the master template feature is enabled else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_override_settings(`
No params
`) { ... }`

Example

Example 1: Default usage

				
					if ( mycred_override_settings() ) {

	// Master Template is enabled

}

mycred_post_is_for_sale

Package: mycred/content Category: Functions

Description

This function checks if a specific post is set for sale in the Sell Content add-on. This can be due to all posts of this type is set for sale or in manual mode, if the post has been selected to be for sale.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the post is for sale else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_post_is_for_sale(`
	`$post_id`	INT or OBJ	Yes	Either a post object ID or a post object.
`) { ... }`

Example

Example 1: Check if the current post, based on the $post global, is set for sale.

				
					global $post;

if ( mycred_post_is_for_sale( $post ) ) {

	// Post is set for sale

}

mycred_post_type_for_sale

Package: mycred/content Category: Functions

Description

This function checks if a given post type is set for sale in the Sell Content settings.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.0

Returns

(bool) TRUE if the post type is set for sale else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_post_type_for_sale(`
	`$post_type`	STRING	Yes	The WordPress post type to check.
`) { ... }`

Example

Example 1: Check if the custom post type “Book“ is set for sale.

				
					$post_type = 'book';

if ( mycred_post_type_for_sale( $post_type ) ) {

	// Post type is set for sale

}

mycred_query_users_total

Package: mycred/balance Category: Functions

Description

This function will query the myCRED log in order to get a given users total balance for a particular point type.

If the given user does not have any log entries, this function will instead return their current balance.

Available since version 1.4.1

Returns

(int | float) The users total balance.

Parameters

	Param	Type	Required	Description
function `mycred_query_users_total(`
	`$user_id`	INT	Yes	The users numeric WordPress ID.
	`$point_type`	STRING	No	The point type key indicating the point type we want to calculate a total for.
`) { ... }`

Example

Example 1: Get the current users default point type total. (recommended usage when you only have one point type setup).

				
					$user_id = get_current_user_id();
$total   = mycred_query_users_total( $user_id );

mycred_rank_has_logo

Package: mycred/rank Category: Functions

Description

This function checks if a given rank has a logo using the has_post_thumbnail function.

This function is only available if the Ranks add-on is enabled.

Available since version 1.0

Returns

(bool) Returns TRUE if the rank has a logo else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_rank_has_logo(`
	`$rank_identifier`	INT or STRING	Yes	Either the ranks post object ID or the ranks exact name.
`) { ... }`

Example

Example 1: Get the current users rank and check if the rank has a logo.

				
					$user_id = get_current_user_id();
$rank_id = mycred_get_users_rank( $user_id );

if ( mycred_rank_has_logo( $rank_id ) ) {

	// Rank has logo

}

mycred_refund_transfer

Package: mycred/transfer Category: Functions

Description

This function attempts to refund a completed transfer.

This function is only available if the Transfer add-on is enabled.

Available since version 1.8

Returns

(bool) Returns TRUE if the refund was successful else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_refund_transfer(`
	`$transfer_id`	STRING	Yes	The transfer ID.
`) { ... }`

Example

Example 1: Basic usage example.

				
					$transfer_id = 'TXT384723943843';
if ( function_exists( 'mycred_get_transfer' ) ) {

	$transfer = mycred_refund_transfer( $transfer_id );
	if ( $transfer === true ) {

		// transfer was refunded

	}
	else {

		// Refund failed

	}

}

mycred_sell_content_new_purchase

Package: mycred/content Category: Functions

Description

This function will attempt to charge a given user for a piece of content that has been set for sale using the Sell Content add-on. If profit sharing is enabled, the function will also payout the post author their share if the user was successfully charged.

This function will not check if the post is set for sale. This should be done before using this function!

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the purchase completed successfully else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_sell_content_new_purchase(`
	`$post`	OBJ	Yes	The post object being purchased.
	`$user_id`	INT	Yes	The users numeric ID.
	`$point_type`	STRING	Yes	The point type used as payment.
`) { ... }`

Example

Example 1: Attempt to charge the current user for purchasing a post.

				
					$post_id = 1;
$post    = get_post( $post_id );
$user_id = get_current_user_id();

// Make sure the post is for sale and we have not paid for it
if ( mycred_post_is_for_sale( $post ) && ! mycred_user_paid_for_content( $user_id, $post->ID ) ) {

	// Now charge
	$result = mycred_sell_content_new_purchase( $post, $user_id, 'mycred_default' );

	// Payment successfull!
	if ( $result ) {

	}

	// Payment declined for some reason
	else {

	}

}

mycred_sell_content_payment_buttons

Package: mycred/content Category: Functions

Description

This function will return all available payment buttons that a user can use, in order to pay for a posts content. This function will check if the user can afford to pay, are not excluded. This function will however not check if the post is set for sale. This needs to be done before using this function.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(bool | string) Returns a string containing button elements for each point type that can be used by the user. Else returns FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_sell_content_payment_buttons(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$post_id`	INT	Yes	The post object ID.
`) { ... }`

mycred_sell_content_post_id

Package: mycred/content Category: Functions

Description

This function attempts to get the current posts ID. It can be used inside a bbPress forum loop in which case the function will attempt to get the forum / topic or replies ID. Must be used inside the loop.

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(int | bool) Either the current post objects ID or FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_sell_content_post_id(`
No params
`) { ... }`

Example

Example 1: Default usage.

				
					$post_id = mycred_sell_content_post_id();

if ( $post_id !== false ) {

}

mycred_subtract

Package: mycred/balance Category: Functions

Description

This function allows you to decrease a users balance by deducting a specific amount from it. This function uses mycred_add to adjust the balance but forces any value you provide to be a negative value.

As of version 1.7, this function will return false if the user is set to be excluded. In previous version, this is ignored.

Available since version 1.0

Returns

(bool) true on success or false on declined transaction.

Parameters

	Param	Type	Required	Description
function `mycred_subtract(`
	`$reference`	STRING	Yes	The reference to log this entry under. You can use your own custom reference or one of the built-in ones.
	`$user_id`	INT	Yes	The users numeric ID.
	`$amount`	INT or FLOAT	Yes	The point amount to deduct from the user. Positive values will be turned negative.
	`$entry`	STRING	Yes	The entry to save in the log for this adjustment.
	`$ref_id`	INT	No	Optional reference ID to save with the log entry.
	`$data`	STRING	No	Optional data to save with the log entry. Note that if you are supply an array, this will be serialized.
	`$type`	STRING	No	The point type key. Should only be used if you are adjusting a custom point type and not the default one.
`) { ... }`

Example

Example 1: Deduct 10 points from a user.

				
					$user_id = get_current_user_id();
mycred_subtract( 'penalty', $user_id, -10, 'Points penalty' );

mycred_transfer

Package: mycred/transfer Category: Functions

Description

This function will returns the myCRED_Transfer object. Note that this function will not populate the object.

This function is only available if the Transfer add-on is enabled.

Available since version 1.8

Returns

(object) Returns the myCRED_Transfer object.

Parameters

	Param	Type	Required	Description
function `mycred_transfer(`
	`$transfer_id`	STRING	No	The transfer ID if you plan on using the object to manipulate or process a transfer. Can be ignored when using the object to render a new transfer form.
`) { ... }`

mycred_use_coupon

Package: mycred/coupon Category: Functions

Description

This function will validate and a given coupon code and if the coupon can be used, redeems the coupon.

This function is only available if the Coupons add-on is enabled.

Available since version 1.0

Returns

(int | float | bool | string) Returns FALSE if the coupon can not be used, a string if the coupon is not valid or the users balance after the coupon was applied if the coupon is valid and was successfully used.

Error Codes

You can use the mycred_get_coupon_error_message function to convert an error code into a readable message.

Error Code	Description
`invalid`	The coupon code or user ID is invalid. Remember that codes are case sensitive.
`expired`	The coupon has expired. This occurs if an expiration date has been reached or the maximum usage limit has been reached.
`user_limit`	User limit reached.
`min`	The user does not meet the minimum balance requirement set for this coupon.
`max`	The user does not meet the maximum balance requirement set for this coupon.
`excluded`	The user is excluded from the point type that the coupon is set to payout.

Parameters

	Param	Type	Required	Description
function `mycred_use_coupon(`
	`$code`	STRING	Yes	The coupon code.
	`$user_id`	INT	Yes	A numeric user ID that will receive the points if the coupon is valid.
`) { ... }`

Example

Example 1: Apply a posted coupon code to the current user.

				
					$user_id = get_current_user_id();
$code    = $_POST['coupon'];

$results = mycred_use_coupon( $code, $user_id );

if ( mycred_coupon_was_successfully_used( $results ) ) {

	// Coupon was successfully used

}
else {

	// Something went wrong

}

mycred_user_can_transfer

Package: mycred/transfer Category: Functions

Description

This function checks if a user can afford or allowed to make a transfer, of a specified amount of points. The function will check to make sure:

A users balance does not go below zero if the transaction would be approved. You can use the mycred_transfer_limit filter to adjust this and allow transfers that would bring a users balance into the negative.
The transfer is within the users limit (if limits are enforced).

This function is only available if the Transfer add-on is enabled.

Available since version 1.0

Returns

(int | float | string) Returns TRUE if the user can make a transfer and there is no transfer limit set. If a limit is set but the user can make the transfer, the function will return the amount remaining. Else returns an error code.

Error Codes

Error Code	Description
`low`	The user can not afford to transfer the given amount or the users balance has reached zero.
`limit`	The set limit has been reached.

Parameters

	Param	Type	Required	Description
function `mycred_user_can_transfer(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$amount`	INT or FLOAT	No	Optional amount that the user is requesting to transfer. If not set the users current balance is used to check for solvency.
	`$point_type`	STRING	No	The point type key used for this transfer. Defaults to the default point type.
	`$reference`	STRING	No	Optional reference to check for limits. This should only be used when a limit is being enforced.
`) { ... }`

Example

Example 1: Check if the current user can make a 10 point transfer.

				
					$user_id = get_current_user_id();

if ( mycred_user_can_transfer( $user_id, 10 ) ) {

	// User can transfer

}

mycred_user_paid_for_content

Package: mycred/content Category: Functions

Description

This function checks if a given user has a valid and active payment for a specific post that is set for sale.

This function also checks if a purchase has expired. For this reason it can not be used to check if a user has made any payment for this content, only if that payment exists and has not yet expired (if used).

This function is only available if the Sell Content add-on is enabled.

Available since version 1.7

Returns

(bool) TRUE if the user has paid and the purchase has not expired else FALSE.

Parameters

	Param	Type	Required	Description
function `mycred_user_paid_for_content(`
	`$user_id`	INT	Yes	The users numeric ID.
	`$post_id`	INT	Yes	The post objects ID.
`) { ... }`

Example

Example 1: Check if the current post is set for sale and if it is, if the current user has paid for it.

				
					global $post;

$user_id = get_current_user_id();
if ( mycred_post_is_for_sale( $post ) && mycred_user_paid_for_content( $user_id, $post->ID ) ) {

	// Post is for sale and the user has paid

}