As we approach the final release date of July 13th, 2022 here are the changes since the last major tag we gave you all.

There have been a significant number of bug fixes, but we wanted to call attention to some of the larger changes that might pose an issue for developers as they integrate with EDD.

Reporting Changes

We’ve made a few changes related to the reports to help give store owners an actionable set of information on the ‘Dashboard’ of reports. Many of these changes came after we’ve had a chance to use Easy Digital Downloads 3.0 on our own site, for our daily business operations.

The first thing you’ll notice is that we’ve consolidated some of the ’tiles’. We reduced the number of tiles in this Dashboard to make the overall view much more useful.

We’ve also been focused on fixing some issues around reporting with Timezones. As of EDD 3.0 all dates recorded in the database are in UTC. By doing this we gave ourselves a point of reference, so that we can always show the store’s reports based on the Timezone setting defined in the general WordPress settings.

Order status helper functions

As we started focusing on not just reporting on Gross and Net stats, we also found it necessary to define some ‘grouped’ order status keys. The following functions are helper functions to get specific order status that should be grouped. Each of these functions also contains a similar filter to allow extensions and customizations to add their own statuses.

edd_get_gross_order_statuses()

Returns an array of order status keys that should be used when wanting orders that should be considered part of a ‘gross’ report.

edd_get_net_order_statuses()

Returns an array of order status keys that should be used when wanting orders that should be considered part of a ‘net’ report.

edd_recoverable_order_statuses()

Returns an array of order status keys that can be used in the core payment recovery feature.

edd_get_complete_order_statuses()

Returns an array of order status keys that are considered ‘complete’. This means they have hit the end of any automated purchase process and no further action needs to be taken at this time.

edd_get_incomplete_order_statuses()

Returns an array of order status keys that are incomplete. This includes things like pending, abandoned, processing, failed or cancelled.

edd_get_refundable_order_statuses()

Returns an array of order status keys that can be refunded.

edd_get_deliverable_order_item_statuses()

Returns an array of order item status keys that should be considered when delivering files. Note that in EDD 3.0, deliverability should be handled at the individual order item level, since one order can contain multiple items with different statuses.

Enabled block editor on Download post type

The download custom post type is now available in the REST API, so your product pages can now be edited with the block editor.

Language files removed

We’ve removed all of our translation files from our package, in order to rely on the WordPress Translation community. We found a number of translation files that were out of date and causing fatal errors due to being incorrectly translated, so we felt it was best to remove them from our plugin entirely, and allow them to be downloaded from translate.wordpress.org.

On-the-fly Backwards Compatibility

We know that keeping stores accepting payments is important, and from day one of EDD 3.0’s development, we wanted to allow new purchases to be able to be completed, while the site was migrating existing payment data.

We’ve taken this a step further, so that when renewals are processed with Recurring Payments or licenses keys are interacted with (checking for updates, activating, deactivating, or checking), that these actions complete successfully with a ‘semi-backwards compatible’ layer of EDD that ensures critical functionality will still work.

We’ve also added the edd_v3_migration_pending option so that you can identify when a migration is either pending start or running. For instance, you may have seen this on our site a few weeks back while we were running this migration ourselves:

Other Bug Fixes and Changes

• Order details will now always show quantities for items.
• Improved performance getting cart total, by making tax calculations more efficient.
• Added a new Currency class, to help support multi-currency stores.
• Filters were added to the discount list table.
• Added a new edd_is_cart_empty() helper function.
• Improved performance of status calculations for downloads.

So what is next?

Well, now that we’ve tagged our final release, we’re going to be pushing this to WordPress.org as a ‘development version’ in order to allow translators to start translating all the new strings.

Shortly after that we will tag our final release on WordPress.org and we’ll go live on July 13, 2022!

As always with large releases like this, especially ones that are moving data around, we would suggest making backups of your site and database prior to any changes being made, as well as testing this out on a staging or local copy of your site first! We’ve tested it extensively and are already running this on our site, but it is always good practice to try it in staging first.

Thanks for your help and support!

Important Note: This beta release is NOT production ready. It should only be tested on development sites. Do not install it on your live site.

Migration fixes

We discovered that migrated order totals could be incorrect if the order had a fee applied that affected the entire order (as opposed to being linked to an individual item). This has now been resolved.

While fixing the fee issue, we also found a few problems when migrating data from very old versions of Easy Digital Downloads — we’re talking back to 2013. Back then, individual payments didn’t even store things like the subtotal or exact discount amount, and that led to unexpected results when the data was migrated to the 3.0 format.

Orders with discounts from that period still may not be perfect, but we’re confident we’ve done the best we can given the limited data from that era. It won’t be any worse than EDD 2.10, it’s just that EDD 3.0 exposes the problems that exist in 2.10 and are simply hidden. For example: if a discount amount wasn’t saved with an old EDD order, EDD 3.0 will show the discount amount as $0.00. That’s not technically correct; there was a discount amount, but because EDD never stored it we don’t know what it is.

Other migration fixes include:

• Undefined index errors when migrating some order addresses.
• When migrating tax rates via the CLI we now show the before and after count.
• Some very old PayPal orders didn’t have their transaction IDs migrated. This is because old orders didn’t store transaction IDs the way we do now, and they only existed in order notes. These are now migrated over.
• Some currency codes were saved (and thus also migrated) in lowercase, which caused unexpected results in our UIs. We now ensure all currency codes are uppercase when migrated.

The sales log has been removed

The sales log has historically existed because it was too difficult for us to query on payments directly, due to storing data in post meta. EDD 3.0 has made the sales log no longer necessary, as we can now very easily query order data. However, the UI still existed.

We made the decision to remove it when we found a bug: refund records were being included in the sales log incorrectly. Fixing that issue actually proved to be more complicated than expected, to the point where it would take less time to just remove the sales log and instead add the one missing feature to the main orders page: the ability to filter by download (product).

So there’s a shiny new feature for you!

Other bug fixes

• EDD_Payments_Stats methods returning unexpected results.
• edd_store_discount() had the default value for its second parameter changed from null to 0, which broke backwards compatibility. This has now been reverted.
• The edd_post_insert_discount hook wasn’t firing after adding a discount code from the admin UI. This caused at least one add-on to stop working with EDD 3.0.
• The Discount API endpoint wasn’t 3.0-ready.
• Negative fees were showing as positive on the admin orders UI.
• Adding a manual order now supports inclusive taxes.
• Several methods in the EDD_Discount class were missing compared to 2.x. (Such as the get_name() method.)
• The tool for re-counting download stats was incorrectly including refunds. It now counts gross earnings, and the label has been updated to better clarify that.
• Reports: Manually adding an invalid date to the custom range field could cause a fatal error.
• A few discount note functions that were introduced in 3.0 and ultimately never used (due to later refactoring) have been removed. Those functions are: edd_ajax_add_discount_note(), edd_delete_discount_note(), and edd_ajax_delete_discount_note(). These were all AJAX callback functions and were never designed for public use.
• Order item meta arrays were incorrectly being double serialized.

Installing and testing 3.0-beta3

The 3.0-beta3 release can be downloaded from GitHub and installed as normal. If you encounter any bugs, please search through our existing issues. If there’s not already an open issue, you may create a new one (after reading our Contributor Guidelines).

The beta2 release is now available for testing, and in this blog post we’ll go over three of the major changes.

1. The new refunds API has been finalized
2. Templates have been reworked
3. The migration now has step recovery

Important Note: This beta release is NOT production ready. It should only be tested on development sites. Do not install it on your live site.

The new refunds API has been finalized

When we released 3.0-beta1, we made it clear that refunds were still a work in progress, but they have now been completed!

Here are a few notable changes:

• Each order item and fee will have a listing in the modal, and you can select which items to refund. It’s possible to refund a fee without refunding the order items, and vice versa.
• For each item, you can also specify a quantity (if applicable), and how much of that item you want to refund. As an example, for that $10 item I could choose to refund only $5 of it.
• We have added a hook to the modal, which you can use to output custom fields below the table. You can see how we’ve added a checkbox that gives you the option to “Refund transaction in PayPal.”

Let’s talk about that last item for a moment. If you’ve built a custom gateway, you probably want to know how to add your own checkbox and execute custom code when the refund runs. Here’s our implementation for PayPal:

Adding the checkbox to the UI

Here’s what the code looks like to add a checkbox to the UI:

/**
 * Shows a checkbox to automatically refund payments in PayPal.
 *
 * @param \EDD\Orders\Order $order
 *
 * @since 3.0
 * @return void
 */
function edd_paypal_refund_checkbox( \EDD\Orders\Order $order ) {
	if ( 'paypal' !== $order->gateway ) {
		return;
	}

	// If our credentials are not set, return early.
	$key       = $order->mode;
	$username  = edd_get_option( 'paypal_' . $key . '_api_username' );
	$password  = edd_get_option( 'paypal_' . $key . '_api_password' );
	$signature = edd_get_option( 'paypal_' . $key . '_api_signature' );

	if ( empty( $username ) || empty( $password ) || empty( $signature ) ) {
		return;
	}
	?>
	<div class="edd-form-group edd-paypal-refund-transaction">
		<div class="edd-form-group__control">
			<input type="checkbox" id="edd-paypal-refund" name="edd-paypal-refund" class="edd-form-group__input" value="1">
			<label for="edd-paypal-refund" class="edd-form-group__label">
				<?php esc_html_e( 'Refund transaction in PayPal', 'easy-digital-downloads' ); ?>
			</label>
		</div>
	</div>
	<?php
}
add_action( 'edd_after_submit_refund_table', 'edd_paypal_refund_checkbox' );

• Hook into edd_after_submit_refund_table. This hook provides one parameter: the \EDD\Orders\Order object.
• Be sure to check that the order is using your gateway.
• We only show the option if the API keys have been configured.
• Then output markup to show the custom field.

The next step is to actually process the refund. Here’s the code to make that happen:

/**
 * If selected, refunds a transaction in PayPal when creating a new refund record.
 *
 * @param int $order_id ID of the order we're processing a refund for.
 * @param int $refund_id ID of the newly created refund record.
 * @param bool $all_refunded Whether or not this was a full refund.
 *
 * @since 3.0
 */
function edd_paypal_maybe_refund_transaction( $order_id, $refund_id, $all_refunded ) {
	if ( ! current_user_can( 'edit_shop_payments', $order_id ) ) {
		return;
	}

	if ( empty( $_POST['data'] ) ) {
		return;
	}

	$order = edd_get_order( $order_id );
	if ( empty( $order->gateway ) || 'paypal' !== $order->gateway ) {
		return;
	}

	// Get our data out of the serialized string.
	parse_str( $_POST['data'], $form_data );

	if ( empty( $form_data['edd-paypal-refund'] ) ) {
		// Checkbox was not checked.
		return;
	}

	$refund = edd_get_order( $refund_id );
	if ( empty( $refund->total ) ) {
		return;
	}

	edd_refund_paypal_purchase( $order, $refund );
}
add_action( 'edd_refund_order', 'edd_paypal_maybe_refund_transaction', 10, 3 );

• Hook into edd_refund_order. This hook supplies three parameters: the ID of the order being refunded, the ID of the newly created refund object, and a boolean indicating if the entire order was refunded or not.
• Be sure to include a permission check.
• Be sure to check the relevant gateway.
• To get the data from the form you’ll want to run: parse_str( $_POST['data'], $form_data ); Then the posted data will be available in $form_data.
• As a sanity check, we make sure the newly created refund total isn’t empty (0.00).
• Then, finally, you can execute your code to actually process the refund at the gateway. (We call edd_refund_paypal_purchase()).

You can see all our code for this in context in the PayPal Standard gateway file.

Templates have been reworked (but are still backwards compatible!)

We’ve updated the history-downloads.php and history-purchases.php templates to use all new 3.0 functions.

The main motivation behind this change was speed. Working with the legacy EDD_Payment object (and associated edd_get_payment() and edd_get_users_purchases() functions) is a performance hit. We have to navigate through multiple backwards compatibility layers to build up that object.

Prior to making the changes, the purchase history template was running approximately 300-400 queries — sometimes more. That definitely slowed the page down and resulted in a pretty negative experience. After reworking it, we’ve gotten it down to approximately 35 queries. That’s quite an improvement!

So what do these changes actually mean for you?

Every hook executed within those templates that passed through an EDD_Payment object (or array of objects) has been deprecated, and new replacements have been created. For example:

Here’s an example hook in the previous template version:

do_action( 'edd_before_purchase_history', $payments );

This hook has been deprecated because it was built to receive an array of EDD_Payment objects. It has been replaced with this new hook, which instead takes an array of \EDD\Orders\Order objects:

do_action( 'edd_before_order_history', $orders );

That being said, the old hook will still work. We hook into the new action to trigger the old:

add_action( 'edd_before_order_history', function( $orders ) {
	if ( ! has_action( 'edd_before_purchase_history' ) ) {
		return;
	}

	$payments = array();

	if ( ! empty( $orders ) ) {
		$order_ids = wp_list_pluck( $orders, 'id' );
		$payments  = edd_get_payments(
			array(
				'id__in'  => $order_ids,
				'orderby' => 'date',
			)
		);
	}

	do_action( 'edd_before_purchase_history', $payments );
} );

The only thing this means for you is that if you’re hooking into the old action you will see a performance hit, because we will need to load in the EDD_Payment objects for your hook.

Right now the old hooks will not trigger any deprecation notices, as it is still easiest to use them if you need to support both EDD 2.x and 3.0 at the same time. We are planning to add deprecation notices in EDD 3.1. We have no plans to stop the hooks from working entirely.

For a full list of all deprecated hooks, check out our new deprecated-hooks.php file.

The migration now has step recovery

The 3.0 migration has 8 different steps — or 9 if you include the removal of legacy data. In beta1, if the migration process was interrupted 50% through step 4 and you reloaded the page to start again, you would start over at 0% of step 4. So although your progress through the 8 (or 9) main steps could be recovered, the steps within each step could not. This has changed with beta2.

Now, if the migration is interrupted 50% through step 4 and you reload the page to initiate it again, you will resume at 50% through step 4.

Installing and testing 3.0-beta2

The 3.0-beta2 release can be downloaded from GitHub and installed as normal. If you encounter any bugs, please search through our existing issues. If there’s not already an open issue, you may create a new one (after reading our Contributor Guidelines).

What’s next for 3.0?

Our next major goal is to upgrade to 3.0 on one of our own Sandhills product sites. We’ve been hard at work updating extensions — first prioritizing the ones we use internally — so we can upgrade to 3.0. We will be doing this prior to the official 3.0 release.

We don’t have an exact date for this yet, and there are still a few extensions we need to update first, but I suspect you’ll see us with another blog post when it happens so we can tell you all about how it went!

The CSS has been simplified and updated. The new invoices will look slightly different, as the overall appearance and font stack has been modernized, but out of the box, the new invoices should be very similar to the old.

Where version 1.2 really shines is that now, store owners can modify the invoice template. The following template files are now available:

• invoice.php: This is the primary template, and consists only of the basic HTML markup, and some new custom hooks.
• invoice-contacts.php: This template outputs the storefront and customer information.
• invoice-table.php: This template outputs the primary “receipt” of the invoice.
• invoice-additional-info.php: This template includes any custom notes added by the customer, as well as custom notes from the storefront (this is a new setting in 1.2).

As with any EDD templates, these can be overridden by copying them to a directory called edd_templates in the active theme folder.

In addition to the templates, EDD Invoices now includes multiple hooks in the invoice so that a store owner can add additional information wherever it’s needed:

• edd_invoices_invoice_head: This hook fires in the head of the HTML output for the invoice. One new feature is that the invoice stylesheet is now output using this hook. The same hook can be used to load an additional custom stylesheet.
• edd_invoices_invoice_header: This hook is used to output the invoice logo (if set), the invoice number, and (new in 1.2) the order status and purchase date.
• edd_invoices_invoice_contacts: The invoice-contacts.php template is loaded in this hook.
• edd_invoices_invoice_items_table: The invoice-table.php template is loaded in this hook.
• edd_invoices_invoice_additional_info: The invoice-additional-info.php template is loaded in this hook.
• edd_invoices_invoice_footer: EDD Invoices adds action buttons (print, back) using this hook. These are not included in the printed version of the invoice.

Each hook uses either the order object (in EDD 3.0) or the payment object (EDD 2.x).

Some invoice content is output directly in the templates, but some of it requires a bit more logic, so 1.2 also introduces some helper functions:

• edd_invoices_get_order_items: This function gets the necessary information for each item in the order: the item ID, the price, the product name, and the price ID. The data is returned to the template as an array.
• edd_invoices_get_order_discounts: This function gets the discounts applied to the order. In EDD 2.9/2.10, the discount code is displayed on the invoice. Because much more specific information is available in 3.0, those invoices will include the amount of each discount, and (for percentage discounts) the discount rate.
• edd_invoices_get_custom_order_meta: This function gets the customer’s notes and/or VAT for the order. It works for the metadata in both EDD 2.x and 3.0.
• edd_invoices_get_order_date: This function gets the order date, which is a different property in EDD 3.0, and requires a little more fallback work for renewal payments in 2.x.

Functions which output directly to the invoice are in the includes/template-functions.php file.

EDD Invoices 1.2 is ready for Easy Digital Downloads 3.0

Just as orders are stored in a custom database table in EDD 3.0, order meta will be as well. Invoices saves custom meta–the option VAT for the customer and any notes the customer adds to the invoice. Invoices 1.2 will migrate this custom meta to the new order meta table when you upgrade to EDD 3.0.

Additionally, the new templates and hooks use the order object in EDD 3.0. This is both more detailed and simpler than the comparable payment object, and allows store owners to access much more specific information about each order and order item.

One big change is the addition of order sections, which allow necessary, but less immediate, data to be hidden on the initial screen load. Core sections included in Easy Digital Downloads are:

• Customer (default)
• Email
• Address
• Notes
• Logs

Extension authors may want to add their own data to these sections as well. To do so, start with registering the custom section:

add_filter( 'edd_get_order_details_sections', 'prefix_add_custom_order_section', 10, 2 );
/**
 * Adds the custom details as an order section in EDD 3.0.
 *
 * @since 2.3.9
 * @param array  $sections The array of order sections.
 * @param object $order    The order object.
 * @return array
 */
function prefix_add_custom_order_section( $sections, $order ) {

    $sections[] = array(
        'id'       => 'prefix_order_section',
        'label'    => __( 'Custom Section' ),
        'icon'     => 'admin-multisite',
        'callback' => 'prefix_show_custom_order_section',
    );

    return $sections;
}

This will add your new custom section to the end of the array of sections (after Logs). Each section has four parameters:

• id: The unique ID of the section
• label: The label which will show in the navigation menu
• icon: The dashicon to use with the navigation label
• callback: the function which will output the section content

The next step is to build your prefix_show_custom_order_section function. This accepts one parameter, the order object. It would begin with something like this:

/** * Shows the custom order section in EDD 3.0.
 *
 * @param \EDD\Orders\Order object $order The order object.
 * @return void
 */
function prefix_show_custom_order_section( $order ) {
    printf( '<h3 class="hndle">%s</h3>', esc_html__( 'Custom Section Heading' ) );
    // Custom code for the section
}

Custom order data can be varied. EDD Simple Shipping, for example, registers two custom sections: one for the shipping address and one for tracking information. These are displayed as individual metabox style boxes in EDD 2.10, but as order sections in 3.0.

Note that in EDD 2.10, the parameter that’s available to a metabox is just the $payment_id, and in EDD 3.0, the entire order object is available. To be compatible with both versions of EDD, you may want to call a separate function from your prefix_show_custom_order_section function, and just pass the $order->id to it. It’s a little extra work to update the code to work with both the order sections and the edd_view_order_details_billing_after hook, which is what metaboxes in 2.10 would use, but it’s worth doing to seamlessly integrate into the new EDD.

Important Note: This beta release is NOT production ready. It should only be tested on development sites. Do not install it on your live site.

Our goals for the first 3.0 beta

Easy Digital Downloads 3.0 is not yet a finished product. The point of this first beta release is not to test the plugin as a whole, but to focus on these key things:

1. Early testing on our migration process, to ensure all necessary data is migrated to its new place and that there are no issues with the data transfer or backwards compatibility.
2. Giving third party developers a chance to see how the code base has changed in 3.0, and the opportunity to update their extensions to be compatible.

Official extensions that are compatible with 3.0:

The following extensions have been already updated to work with 3.0 and may be used in testing:

• Auto Register, version 1.3.11+
• Braintree Gateway, version 1.1.6+
• Commissions, version 3.4.11+
• Gateway Fees
• PDF Invoices, version 2.2.27+
• Recurring, version 2.10.1+
• Software Licensing, version 3.7+
• Stripe Gateway, version 2.8+
  * When checking out with Stripe, you may see a debug notice about addresses being stored incorrectly. This will be addressed in version 2.8.1.

What’s not ready for testing

Order refunds are still undergoing some changes, particularly with regards to refunding fees, so we do not recommend testing refunds or updating any of your own refund-related code. We hope for this to be ready for the beta2 release.

System requirements

In order to run EDD 3.0 you’ll need to have the following minimum versions:

• PHP 5.6+
• WordPress 4.9+

Note: If you installed EDD 3.0 back in 2018 but have not pulled the release branch since then, we recommend starting with an entirely fresh install. This is because we’ve removed some incremental database upgrades from the 3.0 development branch that were introduced in 2018. If you’re installing or upgrading to 3.0 for the first time then this does not affect you.

Installing 3.0-beta1

The 3.0 beta release can be downloaded from GitHub and installed as normal. After installation, new database tables will be installed in the background and you will be prompted to run the 3.0 migration.

Testing the custom tables migration

In 3.0 we migrate the bulk of EDD data out of the WordPress core tables (posts, postmeta, etc.) and into our new custom tables. This includes:

• Discounts
• Payments
• Customer addresses
• Customer email addresses
• Logs
• Order notes
• Customer notes

The migration can either be performed through an admin UI, or run through WP-CLI using this command:

wp edd v30_migration

While testing the migration, double check that all your data has been migrated successfully and that none has been lost — this is particularly true of any custom data you may have added.

Custom payment meta to watch out for

_edd_payment_meta

If you’ve added any custom keys to the _edd_payment_meta array then those will be inserted into our new wp_edd_ordermeta table using the key payment_meta. Just like before, this will be saved as a serialized array.

Note: Calls to edd_get_payment_meta( $payment_id, '_edd_payment_meta' ) are still fully backwards compatible and will include your custom keys/values. However, the backwards compatibility layers do mean that this old method will be slower than our newer edd_get_order_meta() functions so we recommend updating if possible.

Cart item options

In 2.9, _edd_payment_meta included an array that looked like this:

array(
    'cart_details' => array(
        array(
            'item_number' => array(
                'options' => array(
                    'price_id' => 1,
                    'quantity' => 1,
                    // More
                )
            )
        )
    )
)

Any keys added to that options array will be migrated to our new wp_edd_order_itemmeta table. This is meta associated with an individual order item, rather than the order as a whole.

Note: Retrieving this information via edd_get_payment_meta() or edd_get_payment_meta_cart_details() is still fully backwards compatible in 3.0. However, the backwards compatibility layers do mean that this old method will be slower than our newer edd_get_order_meta() functions so we recommend updating if possible.

Custom meta keys

Any custom pieces of meta data associated with a payment will be transferred exactly over to our new wp_edd_ordermeta table. Only the storage location has changed; the data and format remains exactly the same.

Updating your integrations for 3.0

Plugins can be compatible with both EDD 2.9 and 3.0 at the same time. However, a few methods are no longer compatible with 3.0 and your code may need to be updated accordingly.

Ensure you’re not using “post” helper functions on payments, discounts, or logs

In 3.0 you can no longer use “post”-related helper functions on payment, log, or discount code objects. This includes get_post(), get_post_meta(), and more. You will need to update your code to use our wrapper functions instead.

Here’s a detailed list of examples:

• Payments
• Discounts
• Logs

Payments/orders

Note: in 3.0, payments are now referred to as “orders”, which is reflected in the new function names.

Retrieving a payment/order

// NO LONGER VALID
$payment = get_post( $payment_id );

// Valid in both 2.9 and 3.0
$payment = edd_get_payment( $payment_id );

// Valid in 3.0 only
$payment = edd_get_order( $payment_id );

Retrieving meta attached to a payment/order

// NO LONGER VALID
$meta = get_post_meta( $payment_id, 'your_meta_key_here', true );

// Valid in both 2.9 and 3.0
$meta = edd_get_payment_meta( $payment_id, 'your_meta_key_here', true );

// Valid in 3.0 only
$meta = edd_get_order_meta( $payment_id, 'your_meta_key_here', true );

Adding or updating payment/order meta

// NO LONGER VALID
update_post_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

// Valid in both 2.9 and 3.0
edd_update_payment_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

// Valid in 3.0 only
edd_update_order_meta( $payment_id, 'your_meta_key_here', 'your meta value' );

Querying for payment/order records

// NO LONGER VALID
$payments = get_posts( array(
    'post_type'   => 'edd_payment',
    'post_status' => 'publish'
) );

// NO LONGER VALID
$payments = new WP_Query( ( array(
    'post_type'   => 'edd_payment',
    'post_status' => 'publish'
) );

// Valid in both 2.9 and 3.0
$payments = edd_get_payments( array(
    'status' => 'publish'
) );

// Valid in 3.0 only
$payments = edd_get_orders( array(
    'status' => 'complete'
) );

Discounts

Retrieving a discount code

// NO LONGER VALID
$discount = get_post( $discount_id );

// Valid in both 2.9 and 3.0
// Get by ID
$discount = edd_get_discount( $discount_id );

// Get by code
$discount = edd_get_discount_by_code( 'BFCM2021' );

Querying for discount codes

// NO LONGER VALID
$discounts = get_posts( array(
    'post_type'   => 'edd_discount',
    'post_status' => array( 'active', 'inactive' )
) );

// Valid in both 2.9 and 3.0
$discounts = edd_get_discounts( array(
    'post_status' => array( 'active', 'inactive' )
) );

Retrieving meta attached to a discount

// NO LONGER VALID
$meta = get_post_meta( $discount_id, 'your_meta_key_here', true );

// Valid in both 2.9 and 3.0
$discount = edd_get_discount( $discount_id );
$discount->get_meta( 'your_meta_key_here', true );

// Valid in 3.0 only
edd_get_adjustment_meta( $discount_id, 'your_meta_key_here', true );

Adding or updating meta

// NO LONGER VALID
update_post_meta( $discount_id, 'your_meta_key_here', 'your meta value' );

// Valid in both 2.9 and 3.0
$discount = edd_get_discount( $discount_id );
$discount->update_meta( 'your_meta_key_here', 'your meta value' );

// Valid in 3.0 only
edd_update_adjustment_meta( $discount_id, 'your_meta_key_here', 'your meta value' );

Logs

EDD has a class called EDD_Logging, which is available in 2.9 and fully backwards compatible in 3.0. If your code needs to be compatible with both versions, ensure you use this class for all querying and inserting.

Querying logs:

global $edd_logs;
$edd_logs->get_logs( $object_id, $log_type, $page_number );

Inserting a log:

global $edd_logs;
$edd_logs->insert( array(
    'log_type'    => 'gateway_error',
    'post_parent' => $download_id
) );

EDD 3.0 also comes with several new functions. Logs are split up into different database tables according to type: file download logs, API request logs, and generic logs. Here are the new functions for generic logs:

Querying logs:

$logs = edd_get_logs( array(
    'type'    => 'gateway_error',
    'user_id' => $user_id
) );

Inserting a log:

edd_add_log( array(
    'object_id'   => $object_id,
    'object_type' => $object_type,
    'user_id'     => $user_id,
    'type'        => $log_type,
    'title'       => $log_title,
    'content'     => $log_content
) );

Update raw queries on the wp_posts database table

In 3.0, most data has been migrated out of wp_posts and wp_postmeta. As a result, if you’re performing any raw queries on those tables, you may need to update your integration to query on our new tables instead in 3.0.

Here’s a before and after example of one of our own queries for download logs:

2.9 query on the posts/postmeta tables:

SELECT post_parent as downloaded_product_id, COUNT(post_parent) AS number_of_downloads, COUNT(DISTINCT meta_value) AS unique_passes_used
FROM {$wpdb->posts} p
LEFT JOIN {$wpdb->postmeta} pm ON pm.post_id = p.ID
WHERE meta_key = '_edd_log_all_access_pass_id'
AND meta_value LIKE '%_{$all_access_product_id}_%'
AND post_date_gmt > %s
AND post_date_gmt < %s
GROUP BY post_parent
ORDER BY COUNT(post_parent) DESC;

3.0 query on the file_downloads/file_downloadmeta tables:

SELECT product_id as downloaded_product_id, COUNT(product_id) as number_of_downloads, COUNT(DISTINCT meta_value) as unique_passes_used
FROM {$wpdb->edd_logs_file_downloads} l
INNER JOIN {$wpdb->edd_logs_file_downloadmeta} lm ON l.id = lm.edd_logs_file_download_id
WHERE meta_key = '_edd_log_all_access_pass_id'
AND meta_value LIKE '%_{$all_access_product_id}_%'
AND date_created > %s
AND date_created < %s
GROUP BY product_id
ORDER BY COUNT(product_id) DESC

With custom queries like this, you will need to load one version if the site is running EDD 2.9 or lower, and another version if the site is running 3.0+.

Reporting issues

EDD 3.0 is still in active development on GitHub. If you encounter any bugs, please search through our existing issues. If there’s not already an open issue, you may create a new one (after reading our Contributor Guidelines). Please prefix all issues with “3.0 -” so we know it pertains to the 3.0 release.

Apple/Google/Microsoft Pay support

The long-awaited Payment Request Button feature has arrived in Easy Digital Download’s Stripe integration. Payment Request Buttons (or PRB, for short) is what Stripe calls it’s dynamic integrations for Apple Pay, Google Pay and the new Microsoft Pay.

Payment Request Buttons are supported on Single Download pages and Download lists using the [​downloads] shortcode as a “Buy Now” payment method. You can also enable the Payment Request Button on EDD’s Checkout page, where it will be the default payment method if the visitor’s browser supports it.

Visitors will be provided with the appropriate payment option, depending on their platform and/or browser. You can find the details about what operating systems and browsers are supported for each digital wallet service by viewing Stripe’s Payment Request Button documentation.

Stripe Checkout modal replacement

Almost a year ago, Stripe deprecated the ‘Stripe Checkout’ modal that some store owners preferred. This was in an effort to introduce the SCA features as well as their new Checkout experience. While there was nothing we could do about it’s deprecation, we chose to provide a similar purchase experience.

We’ve re-created the Stripe Checkout modal using Stripe Elements. While it is not a stylistic match for the Legacy Checkout product, the functionality remains similar so that store owners can once again use the modal to provide a fast and secure purchase experience, without the need of a cart or checkout page.

Split card fields

In version 2.7 of Stripe, we moved to using Stripe Elements to render the credit card fields. These secure fields, which are provided directly from Stripe’s library look like this.

While some people prefer the combined card field appearance which contains the card number, expiration date, and CVV, it does not work with everyone’s design preferences. In version 2.8 of our integration, we’ve added a checkbox, allowing store owners to have split card fields.

Other improvements

• Option to reject Pre-Paid cards.
• Automatically set the new card as the default if the customer has removed all cards.
• Updated Stripe Library to 7.47.0.
• Bump Stripe API Version to 2020-03-02.
• Send the EDD customer name when creating the Stripe customer object.
• Preemptive updates to allow for EDD 3.0 support.

Notable bug fixes

• Improved PHP 7.3 and 7.4 compatibility.
• Avoid Javascript errors on checkout when cart total is 0 or the page is loaded over http.
• When pre-authorization was allowed and SCA challenges were required, the charges could not be approved.
• Improved localization by fixing incorrect text domains and properly running error messages through translation functions.
• Expired cards did not display properly when managing payment methods and could not be deleted.

Using the beta

Easy Digital Downloads Stripe 2.8 Beta 1 is available to all valid license key holders either via direct download within your account, or you can receive betas in your WordPress admin by enabling updates to betas at Downloads > Tools > Beta Versions.

WordPress 5.5 includes support for auto-updating themes and plugins. Version 3.6.12 of Software Licensing includes updates to the plugin and theme update classes, as well as how they are implemented in our sample code, which users who want to support auto-updates will want to implement.

The new versions of the update classes are:

• EDD_Theme_Updater — 1.1.0
• EDD_SL_Plugin_Updater — 1.8.0

Changelog:

• The theme updater class now populates the no_update property of the WordPress theme update transient
• The plugin updater class adds plugin and id to the plugin version information which is added to the WordPress plugin update transient (the no_update property population was initially added in Software Licensing 3.6.10)

The way theme and plugin authors initialize the updater classes will also need to be updated to work with the WordPress scheduled task. Plugin authors will note that the edd_sl_sample_plugin_updater function now uses the init hook, instead of admin_init. Both this function and the comparable updater method in the theme-updater-admin.php file now include a check for whether a cron job (scheduled task) is running, as well as the user privilege level.

Once you have updated your theme or plugin code to include these changes and it’s on your users’ sites, they will be able to enable auto-updates.

Documentation:

• Software Licensing – Updater Implementation for WordPress Themes
• Software Licensing – Updater Implementation for WordPress Plugins

Valid license holders can get these new sample files from within the Downloads section of your account.

Taxes

In a previous update we showed some improvements to our Tax UI. Since then we’ve made a few more significant changes and fixes that should be noted.

Deprecated the “Default Tax Rate”

As we moved forward with the improvements to the tax features of Easy Digital Downloads, we realized that the ‘Default Tax Rate’ was a setting that ultimately caused problems with our new method of reporting on taxes. It also proved to be a concern as taxes should be applied to a region, but a default tax rate has no region. As such, if Easy Digital Downloads detects a ‘Default Tax Rate’, we are letting stores know this is no longer supported and a region specific tax rate should be identified.

Tax rate improvements

We’ve worked towards making managing tax rates easier in 3.0. On top of the new UI for managing taxes we’ve fixed a few cases where users could add multiple active tax rates for an entire country both in the UI as well as during the migration process.

We’re also planning to include auto-saving tax rates, negating the need to ‘save changes’ after each tax rate modification. This will be done in our Post-Alpha phase.

We’ve also identified and fixed a bug in the migration where a tax rate was being incorrectly rounded up or down to meet the currency decimal point defined by the store’s default currency.

Reporting updates

One of the most improved features of Easy Digital Downloads 3.0 is the reporting system. Thanks to a large amount of database changes and custom tables, the team has been able to improve reporting. The most recent focus was finalizing the UI around reports to make things consistent and accurate no matter what report you are viewing.

Gross/Net status functions

To assist in the accurate reporting in all aspects of Easy Digital Downloads, we’ve introduced two functions which return statuses of orders that would be considered to affect gross and net statistics.

edd_get_gross_order_statuses()

edd_get_net_order_statuses()

These two functions also include filters to allow extension developers to include their own statuses in these calculations, if they are needed. The goal with these two functions is to use a Don’t Repeat Yourself (DRY) method of when to include an order when calculating statistics.

Date ranges in reports

As any developer knows, dates can be difficult. We’ve put some significant effort over the last couple months making sure that when viewing reports, that it is clear that the date ranges are clear and match the expected outcomes. This has caused us to make some significant updates to the filter handlers for reporting.

We’ve also worked on fixing some inconsistencies in the reports that caused the edges of date ranges to not be included in the requested reports. This was a bug that presented itself in current versions of EDD, and thanks to the new reporting APIs, was an easy fix with the new 3.0 data structure.

Improved customer statistics

In previous versions of EDD, our customer reporting statistics for lifetime value and lifetime purchase counts were all ledger based. As new orders were placed or refunded we would simply take the existing value, and add or subtract the modified amount. This could lead to inaccurate reporting and forced us to introduce a tool to ‘recalculate stats’ that needed to be used more frequently than we liked to see.

In 3.0, again thanks to the new database structure, it is an insignificant process for us to quickly, and accurately calculate a customer’s statistics without needing a ledger. When an order is modified for a customer, we quickly recalculate the entire lifetime value and purchase count of the customer, avoiding inaccuracies due to ledger inconsistencies.

The above change, however, does remove the ability to directly affect a customer’s lifetime value or purchase count. As of 3.0, the methods to increase a customer’s value or purchase count by an arbitrary amount are deprecated.

Customer updates

One of the most significant changes to the customer feature of Easy Digital Downloads comes in how both physical addresses and email addresses are managed. Both email addresses and physical addresses have custom tables instead of storing this data in meta, which significantly improves the performance of looking up customers.

Physical address improvements

In recent changes, we’ve introduced the concept of physical address ‘types’ as well as a way to identify what the ‘primary’ physical address is. While Easy Digital Downloads core only supports the billing address out of the box, extensions like Simple Shipping can add in shipping addresses, which will allow each customer to have multiple types of primary addresses, for use in future updates to both EDD and extensions.

Avoid duplicate address data

Our previous methods of storing physical address data resulted in a large number of duplicated addresses for customers. We’ve made some drastic improvements to the address validation before inserting new addresses into the customer record so that we don’t fill your database with duplicate data, including during the migration process.

UI and accessibility updates

After all of the work that was done in an effort to improve the performance and data structures, we needed to make some significant updates to the UI to reflect these changes. With that, we took the opportunity to improve not just the overall UI, but the mobile-friendly access, as well as accessibility. While we aren’t done yet we’ll be making further improvements as we near the 3.0 release, and shortly after it. Some of the areas where we’ve put in the most effort to improve the UI are:

• Order details
• Order list tables
• Tax rates
• Settings
• Download Post Type Metaboxes

While we aren’t fully done with improving the accessibility of the UI and making things more semantic when it comes to our form inputs, you can follow along here. Note this is a living document and is subject to change.

What is next…

We’ve split the last part of this development into two projects:

• Pre-Alpha
• Post-Alpha

At Sandhills development, we like to use our software internally prior to any beta release. This is so we can identify any issues we find internally before releasing them to our customers, even in a beta phase.

Our project for Pre-Alpha are changes that we have to complete prior to when we start internally testing on our sites, and getting all of our extensions updated to support Easy Digital Downloads 3.0. Upon completion of the Pre-Alpha project we’ll shift our focus to extension releases that make them compatible with 3.0 ahead of release, so you shouldn’t have to worry about your extensions working with 3.0 after release.

Once we’re running an alpha on our own data sets, we’ll be shifting our focus to Post-Alpha project issues, after which, we will be publishing our first beta for public testing.

Software Licensing version 3.6.10

Our focus for this update was to address a large number of lingering issues. We made twenty separate improvements to Software Licensing in version 3.6.10.

The complete list of items addressed:

• Fix: When Apache forced trailing slashes, update packages could fail to be downloaded.
• Fix: When upgrading a bundle, the child licenses may not have gotten their price IDs updated.
• Fix: It was not possible to renew multiple licenses for the same product, at the same time.
• Fix: When using bundle licenses with children, the license list table had some performance issues.
• Fix: Child licenses could have a different activation limit than their parent.
• Fix: License counts on the list table for license statuses could be incorrect when child licenses were used.
• Fix: Some of the Readme information was not being parsed correctly after the latest parser update.
• Fix: Searching for a child licenses could give incorrect results, or no results.
• Fix: Updates could intermittently cause the ‘Too Many Redirects’ error.
• Fix: Searching for partial license keys and email addresses could cause PHP notices and/or warnings.
• Fix: When jQuery was being loaded in the footer, some JavaScript errors could occur when managing licenses on the front end.
• Fix: Searching for a non-existent license key, returned all license keys in the list table.
• Fix: Improved the reliability of the checks to make sure an update can be downloaded.
• Fix: When using custom keys, it was possible to use a key length that exceeded the database column’s allowed length.
• Sample Theme:
  • Fix: The sample theme was missing the theme_slug parameter from the API calls.
  • New: The sample theme now supports the item_id parameter.
• Sample Plugin:
  • Fix: The “View Details” link on the plugin list was not always present.
  • Fix: Sample plugin did not define the EDD_SAMPLE_ITEM_NAME string.
• New: Changelogs now support the “Read More” tag, to allow reducing changelog information stored in the get_version API calls.
• Dev: The license list table columns are now filterable and sortable.

Reviews version 2.1.11

Like with Software Licensing, our focus for this update of the Reviews extension was fixing minor issues that have lingered for some time.

We fixed six bugs in version 2.1.11. Those bugs were:

• Fix: Ensure custom code snippets cannot cause undefined index errors in the [downloads] shortcode
• Fix: Enable review request emails to be sent when now is the selected time period
• Fix: Compare version and only show admin notification for upgrade with outdated versions.
• Fix: Verify that orders are complete or published before request review emails sent
• Fix: Remove unused variable $post_id in class review widget
• Fix: Use timestamp $now to ensure review request emails are being sent at correct time relative to store timezone.