EDD_Customer

The EDD_Customer class is used for getting customer data, creating new customer entries, and editing existing customer entries.  The values that may be managed with this class are:

  • user_id
  • name
  • email
  • payment_ids
  • purchase_value
  • purchase_count
  • notes

Getting a Customer

Your reasons for getting Customer data can vary from simply rendering the info to using it for stats or logging or anything else.  Here are the steps to get and render customer information.

Step 1, Get the data

In order to create a Customer object you must pass some sort of identifier when instantiating the class.  This can be email address, Customer ID, or WordPress user ID.

Examples:

Email 
$customer = new EDD_Customer( 'jose@canseco.com' );

Customer ID   
$customer = new EDD_Customer( 33 );

WordPress user ID   
$customer = new EDD_Customer( 96, true );

Note: for the WordPress user ID you must pass a value of true as the second parameter, so that it knows to look at WordPress rather than EDD.

Step 2, Use the data

Now you can access properties of the customer object like this:

  • $customer->name;
  • $customer->email;
  • $customer->date_created;
  • $customer->purchase_count;
  • $customer->purchase_value;
  • $customer->id; // Customer ID
  • $customer->user_id; // WordPress user ID
  • $customer->payment_ids;

You can echo those, parse them; anything you wish.

Getting Customer Payment Data

The EDD_Customer class has a method called get_payments(). This method will return an array of EDD_Payment objects. Example:

$customer = new EDD_Customer( 33 );

$payments = $customer->get_payments();

Now $payments will hold an array of EDD_Payment objects. For more information on what that array looks like,  please see the docs on the EDD_Payment class.

Creating a Customer

First instantiate an object:

$customer = new EDD_Customer;
Example 1:
Then set up some arguments:
$args = array(
	'user_id'        => 12
	'name'           => 'Jose Canseco',
	'email'          => 'jose@canseco.com',
	'payment_ids'    => '',
	'purchase_value' => '',
	'purchase_count' => '',
	'notes'          => 'Whatever note you\'d like',
);

Note: the user_id above is a WordPress user ID number. It is only required if you want to associate your Customer with a WordPress user.  If not, remove it from the array.

And then run the create method:
$customer->create( $args );
And now at this point your Customer should exist.
Example 2:
The above example shows how to create a customer with all possible options.  The only required option is email, so this would work as well:
$args = array(
	'email' => 'jose@canseco.com',
);
$customer->create( $args );

This creates a customer with only the email address provided, which works just fine.

Updating a Customer

Step 1, Get The Data.

Use the example code from "Getting A Customer" above.

Step 2, Update The Data

There are two ways of updating customer data with EDD_Customer. One is to use the update() method and update multiple fields at one time. 

Example:

$customer = new EDD_Customer( 33 );

$update_args = array(
	'email'          => 'jose@canseco.com',
	'name'          => 'Jose Canseco',
);

Now customer 33 has an updated email address and a new note.

Note: updating the notes field with this method will wipe out any existing notes.  Use the add_note() method mentioned below to add a new note.

Updating Specific Fields

Rather than using the general update() method listed above you should generally try to use one of the helper methods provided below.  These provide specific limited functionality that can help reduce errors.

For each of the following methods you would first instantiate the customer class as above:

$customer = new EDD_Customer( 33 );

attach_payment() and remove_payment()

These are used for attaching and removing payments to and from a customer.  They both take a payment_id as the first variable, and a boolean option as the second. The second will update stats if set to true.

Examples:

$customer->attach_payment( 33, true );

$customer->remove_payment( 33, true );

increase_purchase_count() and decrease_purchase_count()

These are used to increase and decrease the number of purchases made by a single customer.  They both simply take an integer, changing the stored value by that much.

Examples:

$customer->increase_purchase_count( 1 );

$customer->decrease_purchase_count( 1 );

increase_value() and decrease_value()

These are used to increase and decrease the amount spent by a single customer.  They both simply take a decimal number, to two places, changing the stored value by that much.

Examples:
$customer->increase_value( 14.98 );
$customer->decrease_value( 3.00 );

get_notes()

This method returns notes left on the customer's account.  It accepts 2 variables, the first for how many notes you want, and the second is an offset.

Examples:
$customer->get_notes( 5 ); // gets the first 5 notes
$customer->decrease_value( 5, 6 ); // gets 5 notes starting at position 6, so notes 6-10

get_notes_count()

This method returns the number of notes on the customer's account. It takes no input.

Example:
$customer->get_notes_count();

add_note()

This method accepts a string as input, and stores it as a new note on the customer's account. It preserves hard returns, but does not allow HTML.

Example:

$customer->add_note( 'This is a note. Isn\'t that cool?' );

Customer Meta

Arbitrary customer meta may be managed using the meta functions built into the EDD_Customer class.

get_meta( $meta_key = '', $single = true )

get_meta simply takes a meta key and returns the value. If single is set to false it will always return an array.

add_meta( $meta_key = '', $meta_value, $unique = false )

add_meta accepts a meta_key and its value, but it also accepts a boolean for unique.  If the third input is true then add_meta will only succeed if the meta_key does not previously exist. Returns false for failure. True for success.

update_meta( $meta_key = '', $meta_value, $prev_value = '' )

update_meta accepts a meta_key and the new value you wish to set for it. If you have multiple keys of the same name they will all be updated with the new value. The third input accepts a value to compare the previous value against. So if you already have several meta_keys of foo but only one with a value of bar, you could make bar the third input and the update would only occur on that one. Returns false for failure. True for success.

delete_meta( $meta_key = '', $meta_value = '' )

delete_meta will delete all meta data with a matching key. If a value is also passed then both must match. Returns false for failure. True for success.

Customer Email Addresses

Each customer can have multiple email addresses, allowing them to purchase from more than one address, or purchase from one and get support from another.  Each customer will also have a primary email address, which gets used as a default for the customer. In the Customer Management tab the UI looks like this:

The EDD_Customer class allows the developer to removes addresses from a customer and add addressed to a customer as well as make a specific address primary. 

add_email( $email = '', $primary = false )

This function accepts an email address to add to the customer.  If the second input is true, the new email address will be set as the primary address for the customer. Returns false for failure. True for success.

set_primary_email( $new_primary_email = '' )

This function accepts an email address and if the email address is already attached to this customer it will make it the primary email address for that customer. Returns false for failure. True for success.

remove_email( $email = '' )

This function accepts an email address and if the email address is already attached to this customer it removes it from that customer. Returns false for failure. True for success.