Returnline Pro for developers

Returnline Pro is built on Returnline's hooks (see Filters and hooks) and adds a few of its own.

returnline_exchange_options

What a customer may choose instead of an order item: product or variation ID => label. By default the same item, then the product's other in-stock variations.

// Only allow exchanges for the same colour: another size of the same colour.
add_filter( 'returnline_exchange_options', function ( $options, $item ) {
	$bought = wc_get_product( $item->get_variation_id() );
	if ( ! $bought ) {
		return $options;
	}
	foreach ( array_keys( $options ) as $id ) {
		$option = wc_get_product( $id );
		if ( $option && $option->get_attribute( 'pa_color' ) !== $bought->get_attribute( 'pa_color' ) ) {
			unset( $options[ $id ] );
		}
	}
	return $options;
}, 10, 2 );

returnline_order_id_from_number

On the Returns page, guests enter the order number they see. If yours aren't the order IDs, turn the number into the ID:

add_filter( 'returnline_order_id_from_number', function ( $order_id, $number ) {
	$orders = wc_get_orders( array( 'limit' => 1, 'return' => 'ids', 'meta_key' => '_order_number', 'meta_value' => $number ) );
	return $orders ? (int) $orders[0] : $order_id;
}, 10, 2 );

The email address must still match the order's billing email.

returnline_label_added

Fires when a label is attached to a return ($return). Returnline Pro uses it to send the approval email again; add your own, for example to notify the warehouse.

returnline_pro_issue_credit

Issue store credit some other way than a coupon, for example as a balance in a store credit plugin. Return a reference, which is stored as the return's credit_code, or a WP_Error to stop; null (the default) creates the coupon. The credit is still recorded on the order as a manual refund for $amount.

add_filter( 'returnline_pro_issue_credit', function ( $code, $return, $order, $amount ) {
	return my_store_credit_add( $return->email, $amount ); // Your reference for it.
}, 10, 4 );

If the refund then fails, returnline_pro_credit_revoked fires with the reference and the return, so you can take the credit back. After success, returnline_pro_credit_issued fires with the return, the reference, the refund IDs and the amount.

Returnline Pro uses this filter itself for Giftline (below), at the default priority, and leaves a reference another callback already returned alone.

Store credit with Giftline

While Giftline is active, store credit goes to the customer's Giftline balance instead of a coupon:

• giftline_add_credit() adds it to the order's customer, or for a guest order to the credit Giftline keeps for the email address (guest), with source returnline, the return number as reference, the order, and the idempotency key returnline:return:<id>. Calling it again for the same return returns the same entry, so a retried completion never credits twice. Giftline's own "Store credit received" email isn't sent: Returnline's completed email says it.
• The return's credit_code is giftline:<ledger entry ID>. Each refund that records the credit also gets Giftline's _giftline_store_credit (the amount in minor units), as Giftline's own refunds to store credit do, and Giftline's "Refund to store credit" handler is kept out of it, so the credit is only added once.
• If the refund fails, giftline_deduct_credit() takes the credit back (key returnline:return:<id>:revoke) and the return's timeline gets a staff-only credit_revoked entry; the next attempt then uses the key returnline:return:<id>:2 (and so on). For a guest order, the credit is read and taken back with guest => true, so it's always the credit kept for the email address, even when an account has that address. If it can't be taken back (the customer already spent it), the order notes say so, the next attempt reuses the key, so the credit isn't added twice, and it must be for the same amount. An order whose customer account was deleted is credited like a guest order, to its email address.

To keep coupons while Giftline is active:

add_filter( 'returnline_pro_giftline_credit', '__return_false' );

The filter also gets the return (or null where there isn't one, such as the request form's choices), so you can decide per return.

Timeline entries

Returnline Pro logs exchanged, credited, credit_revoked (Giftline credit taken back after a failed refund, staff only) and label entries, which you can rename with Returnline's returnline_event_labels filter.

Reading what Pro stored

Pro's data is on Returnline's ReturnRequest:

Property	Holds
$return->resolution	refund, exchange or credit
$return->items[ n ]['exchange_for']	The product or variation sent instead
$return->exchange_order_id	The replacement order
$return->difference_order_id	The replacement order, when it waits for a price difference
$return->credit_code	The store credit coupon's code, or giftline:<ledger entry ID> for credit added to a Giftline balance
$return->photos	Attachment IDs of the customer's photos
$return->label_id	The return label's attachment ID

Replacement orders, coupons, photos, labels and store credit refunds also carry the meta _returnline_return_id. A store credit refund has _returnline_credit_code (the code), and its coupon _returnline_refund_ids (the refunds); WooCommerce's agentic commerce webhooks report those refunds as store_credit. Replacement orders are created with created_via set to returnline, so you can tell them apart in reports or fulfilment rules.

returnline_pro_lemon_squeezy_product_id

For licensing: the Lemon Squeezy product a key must belong to. You won't need it on a store; it's there for our own builds.