# Returnline Pro for developers - Returnline 1.x documentation

> Filters for exchange choices, your own order numbers on the Returns page, where store credit goes (a coupon, Giftline or your own), the license product, and reacting to labels.

> [!NOTE]
> This is part of **Returnline Pro**.

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.

```php
// 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:

```php
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`.

```php
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:

```php
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.

Source: https://extendiment.com/plugins/returnline/docs/1.x/returnline-pro-for-developers