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();