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
- Email hooks
- Integration hooks
- Wizard and front-end hooks
- Rules and refund filters
- Label and carrier filters
- Guest portal hooks (Pro)
- Internal hooks
- Admin screen extension points
- Templates and data
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 id | |
|---|---|
tsre_customer_return_requested | Return requested (customer) |
tsre_customer_return_approved | Return approved (customer) |
tsre_customer_return_rejected | Return rejected (customer) |
tsre_customer_return_received | Return received (customer) |
tsre_customer_return_resolved | Return resolved (customer) |
tsre_customer_return_cancelled | Return cancelled (customer). Not triggered when the customer cancels. |
tsre_admin_return_requested | Return requested (admin) |
tsre_admin_return_in_transit | Return 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 key | On | Meaning |
|---|---|---|
_tsre_exchange_of | Exchange order | Id of the original order |
_tsre_return_id | Exchange order | Id of the return |
_tsre_exchanged_by | Original order | Id of an exchange order, repeated when there are several |
_tsre_credit_used | Order | Store credit taken for the order, 0 once given back |
_tsre_return_id | Refund | Id of the return the refund was made for |
Exchange orders have created_via set to tsre_exchange.