EDD_Payment

The EDD_Payment class makes it easy to create, edit, and delete payment information in Easy Digital Downloads. Here are some examples:

Example of creating a new payment

$payment = new EDD_Payment();
$payment->add_download( 97 );
$payment->email = 'steve@example.com';
$payment->status = 'complete';
$payment->save();

Example of updating the email on an existing payment:

$payment = new EDD_Payment( 4023 );
$payment->email = 'steve@example.com';
$payment->save();

Available Properties

These are the properties which are available to your object:

• $ID
• $number
• $mode
• $key
• $total
• $subtotal
• $tax
• $fees
• $discounts
• $date
• $completed_date
• $status
• $old_status
• $status_nicename
• $customer_id
• $user_id
• $first_name
• $last_name
• $email
• $address
• $transaction_id
• $downloads
• $ip
• $gateway
• $currency
• $cart_details
• $has_unlimited_downloads
• $pending
• $parent_payment

Available Methods

add_download( $download_id = 0, $args = array(), $options = array() )

This method allows you to add a download to a payment. It accepts three arguments:

$download_id

This is the ID of the download you wish to attach. It’s always an integer.

$args

This is an array that can over-ride these built in defaults:

            'quantity'    => 1,
            'price_id'    => false,
            'item_price'  => 0.00,
            'tax'         => 0.00,
            'fees'        => array()

Fees may be anything required, but follows the format of
add_fee(). For more information see the docs for EDD_Fees.

$options

This is an array that can accept arbitrary options for the download. Examples might be
is_renewal or is_upgrade for the Software Licensing extension.

IMPORTANT: if you add a download to a Completed payment the new download will be set to a zero price. If you add a download to a payment with any other status, that download carries its default financial value, and the total value of the payment increases.

This default behavior may be over-ridden by sending an
item_price in the $args.

remove_download( $download_id, $args = array() )

This method allows you to remove a download from a payment. It accepts two arguments:

$download_id

This is the ID of the download you wish to attach. It’s always an integer.

$args

This is an array that can over-ride these built in defaults:

            'quantity'    => 1,
            'price_id'    => false,
            'item_price'  => 0.00,
            'cart_index'  => false,

NOTE: if your download is variable then the price_id is required so that the proper item is removed.

NOTE: By default remove_download() only removes one item. If you have multiple of the same item you’ll need to use the quantity option in the $args.

get_meta( $meta_key = ‘_edd_payment_meta’, $single = true )

This method gets the meta data associated with a payment. It accepts a meta key and a boolean to request the meta data in single mode or not.

Internally this method runs get_post_meta, but then applies some logic to provide backwards compatibility with EDD 1.5

It then runs apply_filters on
'edd_get_payment_meta_' . $meta_key and then returns the output after one more filter of edd_get_payment_meta

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

This method allows you to update the post meta for a payment. It accepts a meta key, meta value, and a previous meta value for comparison.

Before updating, the meta_key is run through a filter called
'edd_update_payment_meta_' . $meta_key.

The return value is the output of
update_post_meta.

add_fee( $args = ”, $global = true )

This method allows you to attach an arbitrary fee to the payment. It functions exactly like the one in EDD_Fees, please read the documentation there.

remove_fee( $key )

This method allows you to remove a given fee. It functions exactly like the one in EDD_Fees,
please read the documentation there.

remove_fee_by( $key, $value, $global = false )

This method allows you to remove a fee without having to know its position in the fees array. For example, if you have a fee with a label of shipping you could do something like

$payment->remove_fee_by( 'label', 'Shipping' );

The above code would remove the first instance of a a fee with a label of Shipping. If you add the gobal true flag like this:

$payment->remove_fee_by( 'label', 'Shipping', true );

then it’ll remove ALL fees with a label of Shipping.

add_note( $note = false )

This method allows you to attach a note to the payment. Results will look something like this:

update_status( $status = false )

This method allows you to set the status of a given payment. Here are the possible statuses:

• Pending
• Complete
• Refunded
• Failed
• Abandoned
• Revoked

array_convert()

This method allows you to get all available properties as an array. Example:

$payment = new EDD_Payment( 4577 );
$payments_array = $payment->array_convert();

IMPORTANT: properties that have been moved to an array with array_convert will NOT be updated inside that array. If you need an updated version after a change you would need to re-run this method and re-populate your array.

save()

This method takes any changes or updates made by any other method and writes them to the database.

NOTE: if you don’t use save() then none of your changes will actually take place.

Examples

Here are some code examples of some common tasks:

Creating a payment

$payment = new EDD_Payment(); // Instantiates a payment object
$payment->add_download( 12 ); // Adds download id 12 to the payment at it's default price
$payment->email = 'lisa@example.org'; // Email is required for a payment
$payment->status = 'complete'; // Completes the payment
$payment->save(); // Writes to the database any changes that were made

Editing an existing payment

$payment = new EDD_Payment( 42 ); // Loads the information for Payment ID 42
$payment->email = 'john@example.org'; // Changes the email address on the payment
$payment->save();

Changing a payment status

$payment = new EDD_Payment( 1337 );
$payment->status = 'revoked';
$payment->save();

Adding a variable priced download

$payment = new EDD_Payment( 1942 );
$args = array(
    'price_id' => 1, // Variable price ID
    'item_price' => 0.00, // Makes the item free
);
$payment->add_download( 23, $args ); // Adds Download ID 23, variable price 1 to the payment
$payment->save();

Adding a download with options

$payment = new EDD_Payment( 2008 );
$args = array(
    'item_price' => 4.00,
);
$options = array(
    'is_renewal' => true,
);
$payment->add_download( 28, $args, $options );
$payment->save();

Removing a download

$payment = new EDD_Payment( 2008 );
$payment->remove_download( 23 );
$payment->save();

Removing a download with variable pricing

$payment = new EDD_Payment( 2008 );
$args = array(
    'price_id' => 1,
);
$payment->remove_download( 28, $args );
$payment->save();