Pular para o conteúdo principal

Hooks and Filters

This page lists the public actions and filters of ReturnDesk. All of them exist since version 1.0.0. Hooks that only run in the Pro edition are marked Pro.

Every hook, option, table and capability uses the prefix tsre. The PHP namespace is Themesic\Returns. Classes are internal and may change; the hooks on this page are the supported way to extend the plugin.

Status and lifecycle actions​

tsre_return_created​

Action, since 1.0.0. Fires after a return was created, and after automatic approval when that applies.

do_action( 'tsre_return_created', int $return_id, \Themesic\Returns\Model\ReturnRequest $return_request );

tsre_return_status_changed​

Action, since 1.0.0. Fires after a return changed status. This is the hook to use for SMS, automation or notification plugins.

do_action( 'tsre_return_status_changed', int $return_id, string $old, string $new, array $context );

$context always has actor_type (customer, admin or system) and actor_id. It can also have admin_note, reason (a rejection reason), tracking_number and auto (true for automatic approval).

Status actions​

Action, since 1.0.0. One action per status, named tsre_return_status_ followed by the status that was reached. It fires right after tsre_return_status_changed.

do_action( "tsre_return_status_{$to}", int $return_id, array $context );

The statuses are approved, rejected, label_sent, in_transit, received, inspected, resolved and cancelled. A return starts as requested without a status change, so use tsre_return_created for that. tsre_return_status_resolved is also the hook behind the tsre_return.resolved webhook.

add_action( 'tsre_return_status_received', function ( $return_id, $context ) {
    error_log( 'Return ' . $return_id . ' was received.' );
}, 10, 2 );

tsre_credit_issued​

Action, since 1.0.0. Pro. Fires after store credit was issued for a return. It also sends the "Store credit added" email.

do_action( 'tsre_credit_issued', int $customer_id, float $amount, int $return_id );

$amount includes the bonus.

Email hooks​

Email trigger actions​

Action, since 1.0.0. Every ReturnDesk email has a trigger action named like its id, which passes the return id and the context of the event. WooCommerce queues or sends the email from it, so the email settings (enabled, recipients, templates) apply.

do_action( $email_id, int $return_id, array $context );
Email idEmail
tsre_customer_return_requestedReturn requested (customer)
tsre_customer_return_approvedReturn approved (customer)
tsre_customer_return_rejectedReturn rejected (customer)
tsre_customer_return_receivedReturn received (customer)
tsre_customer_return_resolvedReturn resolved (customer)
tsre_customer_return_cancelledReturn cancelled (customer). Not triggered when the customer cancels.
tsre_admin_return_requestedReturn requested (admin)
tsre_admin_return_in_transitReturn in transit (admin)
tsre_customer_return_reminder (Pro)Return reminder (customer)

The Pro email "Store credit added" is triggered by tsre_credit_issued.

tsre_email_return_approved_details​

Action, since 1.0.0. Lets other code add details to the approval email, in both the HTML and the plain text version, for example a prepaid return label.

do_action( 'tsre_email_return_approved_details', \Themesic\Returns\Model\ReturnRequest $return_request, bool $sent_to_admin, bool $plain_text, \WC_Email $email );

tsre_label_download_url​

Filter, since 1.0.0. The address the customer downloads the return label from, shown in the approval email. Empty hides the line. ReturnDesk adds a signed link valid for seven days.

apply_filters( 'tsre_label_download_url', string $url, \Themesic\Returns\Model\Label $label, \Themesic\Returns\Model\ReturnRequest $return_request );

Integration hooks​

tsre_credit_note_requested​

Action, since 1.0.0. Fires once after a return created a WooCommerce refund, so an invoicing or PDF plugin can issue a credit note. See Integrations.

do_action( 'tsre_credit_note_requested', \WC_Order $order, \WC_Order_Refund $refund );

Delivery is at least once, so check whether you already issued a credit note for $refund->get_id(). It does not fire for store credit or for an exchange without a refund.

add_action( 'tsre_credit_note_requested', function ( $order, $refund ) {
    my_invoice_plugin_credit_note( $order->get_id(), $refund->get_id() );
}, 10, 2 );

tsre_unit_refund​

Filter, since 1.0.0. The refundable value of one unit of an order line, tax included. Lets an integration take out what must not be paid back, for example the sign-up fee of a subscription. The result is never negative.

apply_filters( 'tsre_unit_refund', float $unit, \WC_Order_Item_Product $item );

Wizard and front-end hooks​

tsre_start_return_url​

Filter, since 1.0.0. The address the Start a return button block points to. In the Pro edition signed-out visitors are sent to the guest portal through this filter.

apply_filters( 'tsre_start_return_url', string $url, bool $logged_in );

tsre_load_frontend_assets​

Filter, since 1.0.0. Whether the front-end stylesheet and script of the returns screens load on this page. The default is true on the My Account returns pages only.

apply_filters( 'tsre_load_frontend_assets', bool $load );

tsre_enqueue_frontend_assets​

Action, since 1.0.0. Asks for the front-end stylesheet and script. Call it from a template or shortcode of your own that shows the wizard.

do_action( 'tsre_enqueue_frontend_assets' );

tsre_wizard_resolution_fields​

Action, since 1.0.0. Lets an add-on print more fields on the resolution step. The exchange picker of both editions prints the replacement lists here. Read them with tsre_wizard_resolution_items.

do_action( 'tsre_wizard_resolution_fields', array $view );

tsre_wizard_resolution_items​

Filter, since 1.0.0. The item input of the wizard when the resolution step is saved. The result is checked again by the request validator, so a filter cannot make an unavailable replacement acceptable.

apply_filters( 'tsre_wizard_resolution_items', array $items, array $post, \WC_Order $order, string $resolution );

tsre_wizard_review_details​

Action, since 1.0.0. Lets an add-on show more on the review step, for example the price difference of an exchange (Pro).

do_action( 'tsre_wizard_review_details', array $view );

tsre_exchange_candidates​

Filter, since 1.0.0. Pro. The products offered as the replacement of a returned line. Variable parents are expanded to their variations. Add catalogue items beyond the variations and up-sells of the product. The Lite edition never applies it: its replacements are always the other variations of the same product at the same price.

apply_filters( 'tsre_exchange_candidates', \WC_Product[] $products, \WC_Order_Item_Product $item );

Rules and refund filters​

tsre_unit_refund is described under Integration hooks. tsre_has_pro is internal; see Internal hooks.

Label and carrier filters​

tsre_label_providers​

Filter, since 1.0.0. The label providers. A provider is an object that implements LabelProviderInterface; other entries are ignored, and a later provider replaces an earlier one with the same id. The Pro edition adds EasyPost here.

apply_filters( 'tsre_label_providers', array $providers, \Themesic\WooKit\Settings\Settings $settings );

tsre_label_settings_fields​

Filter, since 1.0.0. The settings fields of the label providers in the Labels section. It starts with the fields the registered providers declare. Use the secret setting type for credentials.

apply_filters( 'tsre_label_settings_fields', array $provider_fields );

tsre_label_parcel​

Filter, since 1.0.0. The parcel sent to the label provider. Keys: weight, length, width, height, weight_unit (kg) and dimension_unit (cm).

apply_filters( 'tsre_label_parcel', array $parcel, \Themesic\Returns\Model\ReturnRequest $return_request );

tsre_manual_label_attachment_id​

Filter, since 1.0.0. The id of the uploaded label PDF that the manual provider should use. 0 means none.

apply_filters( 'tsre_manual_label_attachment_id', int $attachment_id, int $return_id );

tsre_label_lock_timeout​

Filter, since 1.0.0. How many seconds a label job waits for the lock of its return before it gives up.

apply_filters( 'tsre_label_lock_timeout', int $seconds );

Provider API base filters​

Filters, since 1.0.0. The API base address of a provider, without a trailing slash, for sandboxes and tests. Pro.

apply_filters( 'tsre_easypost_api_base', string $base_url );

tsre_webhook_status_map​

Filter, since 1.0.0. Pro. How carrier tracking statuses map to return statuses. The map is keyed by provider id (easypost). Each entry maps a lower case carrier status to in_transit or delivered. Statuses that are not mapped are ignored, and so is any other target.

apply_filters( 'tsre_webhook_status_map', array $map );

Guest portal hooks (Pro)​

tsre_portal_url​

Filter, since 1.0.0. The address of the guest portal, for a portal that lives on another page.

apply_filters( 'tsre_portal_url', string $base );

tsre_client_ip​

Filter, since 1.0.0. The address used for the guest portal rate limit. Forwarding headers are not trusted by default, because anybody can send them. A site behind a trusted proxy returns the right address from here.

apply_filters( 'tsre_client_ip', string $ip );
add_filter( 'tsre_client_ip', function ( $ip ) {
    return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) : $ip;
} );

Only do this when your server really sits behind that proxy.

Internal hooks​

These hooks connect the shared plugin code to the Pro edition. They are internal: not a supported extension point, and they may change in any release without notice. Use the hooks above instead.

tsre_register_services​

Action, since 1.0.0. Internal. Fires once the plugin registered its own services, with the shared container. The Pro bootstrap file (includes/Pro/bootstrap.php, which the main file loads when the build ships it) registers the Pro services here. The Lite build ships no such file and names no Pro class.

do_action( 'tsre_register_services', \Themesic\WooKit\Plugin\Container $container );

tsre_activated and tsre_deactivated​

Actions, since 1.0.0. Internal. Fire when the plugin is activated (after its tables exist) and deactivated. The Pro edition schedules and removes its daily credit expiry and automatic closing jobs here.

do_action( 'tsre_activated' );
do_action( 'tsre_deactivated' );

tsre_has_pro​

Filter, since 1.0.0. Internal. Whether the Pro features are on. It runs only once the Pro bootstrap registered itself, with the value true, so it can switch the Pro features off (tests use this to see the Lite edition) but can never switch them on in the Lite edition.

apply_filters( 'tsre_has_pro', bool $has_pro );

tsre_resolution_handlers​

Filter, since 1.0.0. Internal. The resolution handlers, as a map from resolution (refund, credit, exchange, warranty) to a handler object. Its starting value holds the same-price variant exchange handler that both editions have (exchange); the Pro edition replaces it with its own exchange handler and adds refund (which pays a refund back partly as the store credit the order was paid with), credit and warranty. The filter is only applied while the Pro edition is active; without a refund handler the plugin refunds through the gateway itself.

apply_filters( 'tsre_resolution_handlers', array $handlers );

tsre_refundable_beyond_gateway​

Filter, since 1.0.0. Internal. What an order can give back besides a refund through its payment gateway; the resolution plan caps the refund at the gateway's remaining amount plus this. The Pro edition adds the store credit the order was paid with and still holds. Only applied while the Pro edition is active.

apply_filters( 'tsre_refundable_beyond_gateway', float $beyond, \WC_Order $order, ?\Themesic\Returns\Model\ReturnRequest $return_request );

tsre_admin_action_handlers​

Filter, since 1.0.0. Internal. Extra admin actions: action name (lowercase letters and underscores) to a handler. A name the plugin already uses is ignored. The Pro edition adds its label tools here.

apply_filters( 'tsre_admin_action_handlers', array $extra );

tsre_admin_resolve_plan​

Filter, since 1.0.0. Internal. The plan an admin resolves with, from the fields of the resolve form. The Pro amount editor lowers the amount here. Only refund, credit and base are read back, and each must stay between 0 and the value of the original plan.

apply_filters( 'tsre_admin_resolve_plan', array $plan, \Themesic\Returns\Model\ReturnRequest $return_request, array $post );

Admin screen extension points​

These actions print more on the return screen. The Pro edition uses them, and they are available to other plugins too, but they are lower level than the hooks above.

tsre_admin_label_panel​

Action, since 1.0.0. Prints more label tools in the label panel of the return screen.

do_action( 'tsre_admin_label_panel', \Themesic\Returns\Model\ReturnRequest $return_request, array $labels );

tsre_admin_plan_details​

Action, since 1.0.0. Prints more details of the planned resolution below the amounts and the list of replacements, which the plan panel prints itself in both editions.

do_action( 'tsre_admin_plan_details', \Themesic\Returns\Model\ReturnRequest $return_request, array $plan );

tsre_admin_plan_editor​

Action, since 1.0.0. Prints fields inside the resolve form, such as the Pro amount editor. Read them back with tsre_admin_resolve_plan.

do_action( 'tsre_admin_plan_editor', \Themesic\Returns\Model\ReturnRequest $return_request, array $plan );

Templates and data​

Template overrides​

Copy a file from templates/ in the plugin into yourtheme/returndesk/, keeping the sub folder, to override it. See Blocks.

Capability​

manage_tsre_returns, granted to Administrator and Shop manager. It gates the Returns screens and the staff REST routes.

Tables​

ReturnDesk keeps its data in five tables (with your database prefix), which refer to order ids and are independent of HPOS: tsre_returns, tsre_return_items, tsre_return_events, tsre_credits (Pro data) and tsre_labels. Schema 1.0.1 added the request terms of a returned line (fee_type, fee_value, eu_withdrawal on tsre_return_items) and, on tsre_credits, the return that gave order credit back (return_id) and the refundable amount a return's credit stands for (base_amount). Schema 1.0.2 indexes created_at and resolved_at of tsre_returns. Deleting a site of a network drops its five tables (through wpmu_drop_tables). Settings are one option named tsre_settings. Per-product and per-category rules are stored in the meta key _tsre_rules. Read through the REST API or the hooks where you can.

Order meta​

Meta keyOnMeaning
_tsre_exchange_ofExchange orderId of the original order
_tsre_return_idExchange orderId of the return
_tsre_exchanged_byOriginal orderId of an exchange order, repeated when there are several
_tsre_credit_usedOrderStore credit taken for the order, 0 once given back
_tsre_return_idRefundId of the return the refund was made for

Exchange orders have created_via set to tsre_exchange.