RCP_Membership

The RCP_Membership class was released in version 3.0. It contains information and helper methods about a user's membership.

Getting a membership

The main way to retrieve a membership object is with the rcp_get_membership() function. This requires that you know the membership ID number. Here's an example:

$membership = rcp_get_membership( 123 );

Alternatively, some of our other helper functions will return RCP_Membership objects automatically, including:

  • rcp_get_memberships()
  • RCP_Customer::get_memberships()

Do not create a new instance of the RCP_Membership class manually.

Retrieving membership data

Once you have an RCP_Membership object, you can use it to retrieve all the information about the membership. Here's a list of methods:

get_id()

Returns the ID number of the membership.

get_customer()

Returns the RCP_Customer object for the customer associated with this membership.

get_object_id()

Returns the object ID number associated with this membership. This will be the ID of the membership level.

get_object_type()

Returns the type of object associated with this membership. This will be membership.

get_currency()

Returns the currency code used for this membership's payments, such as USD.

get_initial_amount( $formatted = false )

Returns the amount charged on the initial signup. If $formatted is set to FALSE then just the integer or float value will be returned. If $formatted is set to TRUE then the result will be formatted with the currency symbol. Examples:

$membership = rcp_get_membership( 1 );
echo $membership->get_initial_amount( false );

This will print a plain number, like 14.99.

$membership = rcp_get_membership( 1 );
echo $membership->get_initial_amount( true );

This will add the currency symbol in the correct place, like $14.99.

get_recurring_amount( $formatted = false)

Returns the amount charged for renewal payments. If $formatted is set to FALSE then just the integer or float value will be returned. If $formatted is set to TRUE then the result will be formatted with the currency symbol. Examples:

$membership = rcp_get_membership( 1 );
echo $membership->get_recurring_amount( false );

This will print a plain number, like 50.

$membership = rcp_get_membership( 1 );
echo $membership->get_recurring_amount( true );

This will add the currency symbol in the correct place, like $50.

get_status()

Returns the status of the membership. Will be one of the following:

  • active
  • cancelled
  • expired
  • pending

get_expiration_date( $formatted = true )

Returns the expiration date (or next renewal date) of the membership. If $formatted is set to TRUE then the result will be formatted according to your date/time settings in Settings > General. If $formatted is set to FALSE then the result will be in MySQL format. Examples:

$membership = rcp_get_membership( 1 );
echo $membership->get_expiration_date( true );

This might print: December 31st 2018

$membership = rcp_get_membership( 1 );
echo $membership->get_expiration_date( false );

This might print: 2018-12-31 23:59:59

get_expiration_time()

Returns the expiration date (or renewal date) as a unix timestamp.

get_created_date()

Returns the date the membership was created in MySQL format.

get_trial_end_date()

Returns the date the free trial for this membership ends, in MySQL format.

get_cancellation_date()

Returns the date the membership was cancelled, in MySQL format.

get_times_billed()

Returns the number of times the membership has been billed. This is the number of payments associated with the membership.

get_gateway()

Returns the slug of the payment gateway used for payments.

get_gateway_customer_id()

Returns the customer ID from the payment gateway. This value is not used for all gateways. It's only used when the gateway creates some kind of customer profile, such as in Stripe and Braintree. In Stripe, this value begins with cus_.

get_gateway_subscription_id()

Returns the ID of the subscription in the payment gateway. In Stripe, this value begins with sub_.

get_subscription_key()

Returns the subscription key associated with this membership.

get_upgraded_from()

If applicable, returns the ID number of the membership this one was upgraded from.

get_notes()

Returns a string of all notes associated with this membership.

get_signup_method()

Returns a slug indicating which method was used for creating this membership:

  • live - Created via the registration form.
  • manual - Manually granted by an administrator via the admin area.
  • imported - Imported via a CSV file.

get_card_details()

Returns an array of information about the card stored for this membership. For a Stripe card, the array would look like this:

array(
    'stripe' => array(
        'name' => 'Jane Doe',
        'type' => 'Visa',
        'zip' => '123456',
        'exp_month' => 9,
        'exp_year' => 2020,
        'last4' => '1234'
    )
)

get_payments()

Returns an array of payments made for this membership.

Other helper methods

  • set_status( $new_status ) - Change the status of the membership.
  • set_expiration_date( $new_date ) - Change the expiration date of the membership. The new date should be in MySQL format.
  • calculate_expiration( $from_today = false, $trial = false ) - Calculate a new expiration date. This is used when processing renewals and figuring out what the expiration date should be extended to.
  • is_trialing() - Returns TRUE if the membership is in a trial period. Otherwise returns FALSE.
  • is_active() - Returns TRUE if the membership is active, or FALSE If not.
  • is_paid() - Returns TRUE if this is a paid membership.
  • is_expired() - Returns TRUE if the membership has expired.
  • is_recurring() - Returns TRUE if auto renew is enabled for this membership.
  • set_recurring( $is_recurring = true ) - Change the auto renew value. NOTE: This does not actually cancel or create recurring subscriptions in the payment gateway. This just changes the flag in the RCP records.
  • set_gateway_customer_id( $customer_id ) - Change the gateway customer ID value.
  • get_gateway_subscription_id( $subscription_id ) - Change the gateway subscription ID value.
  • set_subscription_key( $subscription_key = '' ) - Change the subscription key value. You can leave $subscription_key blank to auto generate a key.
  • was_upgrade() - Returns true if this membership was upgraded from another.
  • activate() - Runs the activation process for the membership. This is triggered after a new signup and when payment is received/confirmed. This sends out the welcome email.
  • can_renew() - Determines if the customer is able to renew this membership. This will return FALSE if it's a free membership, or if the membership is active and has auto renew enabled.
  • renew( $recurring = false, $status = 'active', $expiration = '' ) - Renews the membership. This extends the expiration date. Leave $expiration blank to auto calculate the new expiration date.
  • upgrade_possible() - Returns TRUE if this membership can be upgraded to a different membership level.
  • has_upgrade_path() - Returns TRUE if there are upgrade paths available.
  • get_upgrade_paths() - Returns an array of membership levels this membership can be upgraded to.
  • disable() - Disables the membership. The user will no longer be able to renew, cancel, or otherwise see this membership. They will also lose access to any restricted content the membership granted them. This is essentially like deleting a membership.
  • cancel() - Cancels the membership. NOTE: This just updates the status to "cancelled", sends out the cancellation email, and runs a few action hooks. It does not cancel recurring payments (see cancel_payment_profile() for that).
  • can_cancel() - Determines if a gateway subscription can be cancelled. This will return FALSE if auto renew is not enabled or if the membership is inactive.
  • cancel_payment_profile( $set_status = true ) - Cancels recurring billing at the payment gateway. Set $set_status to TRUE if you also want to change the membership status to "cancelled". This then runs cancel() automatically.
  • expire() - Expires the membership and revokes access to restricted content.
  • add_note( $note = '' ) - Add a new note about the membership.
  • can_access( $post_id ) - Determines if the membership allows the customer to view a certain post/page.
  • has_access_level( $access_level_needed ) - Determines if the membership has a specific access level or higher.
  • get_prorate_credit_amount() - Returns the credit amount for the time left on this membership. This credit would be applied if the membership were to be upgraded or downgraded.
  • can_update_billing_card() - Returns TRUE if the billing card can be updated for this membership. This would return TRUE if the gateway supports it and auto renew is enabled.
  • increment_times_billed() - Increments the number of times this membership has been billed for.