Developer reference

Code lives under the ReturnKit\ namespace in includes/. The prefix for options, tables, hooks, query parameters and CSS classes is rtkt_ (rtkt- in CSS).

Shortcodes

[returnkit_withdrawal_button label="Cancel a purchase" class="footer-link"]

Templates

Every customer-facing template can be overridden by the theme. Copy it from wp-content/plugins/returnkit/templates/ to yourtheme/woocommerce/returnkit/, keeping the sub-folder, and edit the copy. Templates are loaded with wc_get_template(), so a child theme's copy wins over the parent's. Each template's header lists the variables it receives, and its @version.

Filters

rtkt_deadline

Change the last moment a return or withdrawal can be requested.

// Give returns until the end of January for December orders.
add_filter( 'rtkt_deadline', function ( $deadline, $order, $type ) {
	$created = $order->get_date_created();
	if ( 'return' === $type && $created && '12' === $created->date( 'm' ) ) {
		return max( $deadline, strtotime( ( (int) $created->date( 'Y' ) + 1 ) . '-01-31 23:59:59' ) );
	}
	return $deadline;
}, 10, 3 );

Not called while the period hasn't started (with When the order is completed, before completion).

rtkt_order_eligibility

Refuse a return or withdrawal for an order that passed every built-in check.

add_filter( 'rtkt_order_eligibility', function ( $result, $order, $type ) {
	if ( 'return' === $type && $order->get_meta( '_wholesale' ) ) {
		$result['ok']   = false;
		$result['code'] = 'status';
	}
	return $result;
}, 10, 3 );

The filter only runs when the order is eligible; a refusal returns before it. The customer sees the message for code.

rtkt_item_excluded

Exclude an order line, or allow one that's excluded. Return the reason shown to the customer, or '' to allow it.

add_filter( 'rtkt_item_excluded', function ( $reason, $item, $product, $type ) {
	if ( 'return' === $type && $product && $product->get_meta( '_final_sale' ) ) {
		return __( 'Final sale items can\'t be returned.', 'my-theme' );
	}
	return $reason;
}, 10, 4 );

Only exclude from withdrawal what the law allows.

rtkt_reasons

Change the reasons offered, as key => label. Keys are stored on the items.

add_filter( 'rtkt_reasons', function ( $reasons ) {
	$reasons['gift'] = 'Unwanted gift';
	return $reasons;
} );

rtkt_client_ip

Change the visitor IP address ReturnKit uses for the rate limit, Turnstile and the IP stored with each request. Runs after Visitor IP address from has been applied. Return a valid IP, or '' for unknown.

add_filter( 'rtkt_client_ip', function ( $ip ) {
	// e.g. a header set by your own trusted edge.
	return isset( $_SERVER['HTTP_X_MY_EDGE_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_MY_EDGE_IP'] ) ) : $ip;
} );

The value is shortened before it's stored when Shorten IP addresses is on.

rtkt_request_number

Change the request number shown to customers and in wp-admin. Default R-{id}.

add_filter( 'rtkt_request_number', function ( $number, $request ) {
	return 'RMA-' . str_pad( (string) $request->id(), 6, '0', STR_PAD_LEFT );
}, 10, 2 );

The search box recognizes R-123 and bare numbers only.

rtkt_request_items

Inspect or change a new request's item rows before it's saved, or return a WP_Error to refuse it with that message. Pro uses it to validate and price exchanges.

add_filter( 'rtkt_request_items', function ( $items, $order, $type ) {
	if ( 'withdrawal' !== $type && count( $items ) > 10 ) {
		return new WP_Error( 'too_many', 'Please contact us to return more than 10 items.' );
	}
	return $items;
}, 10, 3 );

Don't refuse withdrawals with this filter: a valid withdrawal statement must be accepted.

rtkt_new_request_flags

Add flags to a new request. Flags show on the request, in the store email and under the Flagged filter. Pro adds frequent and risky here.

add_filter( 'rtkt_new_request_flags', function ( $flags, $order, $email ) {
	if ( $order->get_total() > 1000 ) {
		$flags[] = 'high_value';
	}
	return $flags;
}, 10, 3 );

Unknown flag keys are displayed as the key itself. Not called for unmatched withdrawals, which always get unmatched.

rtkt_customer_timeline

Change the timeline entries customers see on their request page.

rtkt_email_status_change

Return false to skip the customer email for a status change.

// No "we've received your items" email.
add_filter( 'rtkt_email_status_change', function ( $send, $request, $to ) {
	return 'received' === $to ? false : $send;
}, 10, 3 );

rtkt_approved_email_attachments

Files to attach to the "approved" update email. Pro adds the return label.

rtkt_exchange_options (Pro)

Change the replacements offered for an order line.

add_filter( 'rtkt_exchange_options', function ( $options, $line ) {
	unset( $options[ 123 ] ); // never offer product 123.
	return $options;
}, 10, 2 );

A replacement you add must still be published, purchasable and in stock to be accepted.

Admin filters

Actions

Template actions:

// Post every new withdrawal to an internal system.
add_action( 'rtkt_request_created', function ( $request ) {
	if ( $request->is_withdrawal() ) {
		wp_remote_post( 'https://erp.example.com/withdrawals', array(
			'body' => array(
				'number'    => $request->number(),
				'order'     => $request->order_id(),
				'submitted' => $request->meta( 'submitted_at' ),
			),
		) );
	}
} );

The request object

Hooks pass ReturnKit\Domain\Request. Useful methods: id(), number(), type() (return, exchange, withdrawal), is_withdrawal(), status(), is_closed(), resolution() (refund, credit, exchange), order_id(), order(), customer_id(), email(), name(), note(), currency(), total(), refunded(), credited(), created_gmt(), flags(), has_flag(), items(), qty(), meta( $key ) and get( $column ).

For withdrawals, meta( 'statement' ) holds the frozen statement: name, email, order_number, scope (full or items), items (name and qty), details, note, submitted_at (Unix time) and submitted (ISO 8601, UTC).

Creating requests from code

Every request, from any form, goes through ReturnKit\Domain\Service::create(), which re-checks eligibility and quantities under a per-order lock:

use ReturnKit\Domain\Service;

$request = Service::create(
	$order,                                  // WC_Order
	'return',                                // return | exchange | withdrawal
	array( $item_id => array( 'qty' => 1, 'reason' => 'damaged-or-defective' ) ),
	array( 'source' => 'admin', 'note' => 'Reported by phone.' )
);
if ( is_wp_error( $request ) ) {
	// ->get_error_message() is customer-ready.
}

With source set to admin, eligibility, exclusions and the required reason are skipped (quantities are still checked), the history records a staff action, and the source shows as Created by staff. The usual emails are sent. The other sources are account, guest and form (the general withdrawal form).

Query parameters

Useful when building links. Links that show an order or a request need the secret part (rtkt_key or rtkt_token) unless the visitor is the logged-in customer.

Order numbers

Wherever a customer or staff member types an order number (the guest look-up, the general withdrawal form, Link order, search), ReturnKit runs it through WooCommerce's woocommerce_shortcode_order_tracking_order_id filter, the same one WooCommerce's order tracking uses. Sequential order number plugins that support order tracking work without extra code.

Crash protection

Every hook ReturnKit registers goes through ReturnKit\Core\Safe:

Caught errors are logged (ReturnKit caught an error … and let the request continue) and the latest one is stored in the rtkt_last_error option for a wp-admin notice, shown for 24 hours. Callbacks you add to rtkt_* hooks usually run inside one of these guards, so an exception in them is caught too, but the rest of that step may be skipped. Keep your callbacks defensive.

Because the hooks are registered through closures, remove_action() / remove_filter() can't target them by callback. Use the settings or filters instead.

Constants

The plugin defines RTKT_VERSION, RTKT_FILE, RTKT_DIR, RTKT_URL, RTKT_BASENAME, RTKT_DOCS_URL and RTKT_SUPPORT_URL.

Data the plugin stores

rtkt_requests: id, order_id (0 = unmatched withdrawal), customer_id, email, name, type (return, exchange, withdrawal), status, resolution (refund, credit, exchange), note, source (account, guest, form, admin), currency, total, refunded, credited, exchange_order_id, flags (comma separated), ip, meta (JSON), created_at, updated_at (UTC).

rtkt_request_items: id, request_id, order_item_id, product_id, variation_id, name, qty, unit_value (incl. tax, after discounts), reason (key), exchange_product_id, exchange_name, exchange_price, received_qty, restocked_qty, refunded_qty.

Request meta (JSON): scope, submitted_at, secret (signs the request's links), statement (withdrawals), received (when items were marked received), refunds (WooCommerce refund IDs), label (Pro), anonymized.

Request flags: outside_window, unmatched, email_mismatch, and with Pro frequent and risky.

Log events: created, flagged, approved, received, completed, rejected, cancelled, refunded, refund_failed, restocked, note, message, email_sent, email_failed, email_off, linked, anonymized, and with Pro rule, credited, credit_claimed, exchange_order, exchange_paid, label.

Orders are referenced by ID, so HPOS and legacy order storage both work.

Code map