# Hooks - Depositline 1.x documentation

> The actions and filters for deposit rules, due dates, balance orders, saved-card connectors, conflicts and the settings page, plus the Store API data and WP-CLI commands.

Depositline's hooks are WordPress actions and filters. Put the examples in a small custom plugin or your child theme's `functions.php`. Classes live in the `Extendiment\Depositline` namespace.

A deposit order keeps its products at their full price, with an untaxed negative fee, "Balance, paid later", for what's left. Once the deposit is paid it gets a child balance order (`parent` = the deposit order) with one untaxed fee for the balance. `Extendiment\Depositline\Balance` has the helpers: `is_deposit_order( $order )`, `is_balance( $order )`, `balance_of( $order )`, `parent_of( $balance )`, `amount( $order )`, `due( $order )` (Y-m-d), `outstanding( $order )` and `paid( $order )`. The "Partially paid" order status is `partial-payment` (`wc-partial-payment`).

## Loading

| Hook | What it's for |
|---|---|
| `depositline_loaded` (action) | Depositline has loaded (on `plugins_loaded`), its classes and `DEPOSITLINE_*` constants are available. Start extensions here. |

> [!NOTE]
> `depositline_loaded` doesn't fire while WooCommerce is inactive, nor while another deposits plugin is active (see `depositline_conflicts` below): Depositline is paused then, and only its settings page, importer, WP-CLI commands and a notice load. Code hooked to `depositline_loaded` doesn't run in that state.

## Deposit rules

| Hook | What it's for |
|---|---|
| `depositline_rule` (filter) | A product's deposit rule, after the variation, product, category and store-wide settings are resolved (`$rule, $product`). `$rule` is an array with `mode` (`none`, `optional` or `required`) and `amount` (`"20%"` or `"50"`, an amount per unit). `$product` is a simple product or a variation. Invalid values fall back to no deposit. |
| `depositline_applies` (filter) | Whether a product takes a deposit (`$applies, $product`). Return false for products another plugin collects payment for its own way. Depositline does this itself for Preorderline pre-orders. |

```php
// A 50% deposit, required, on anything over $1,000.
add_filter( 'depositline_rule', function ( $rule, $product ) {
	if ( (float) $product->get_price() > 1000 ) {
		$rule = array( 'mode' => 'required', 'amount' => '50%' );
	}
	return $rule;
}, 10, 2 );

// Never a deposit on gift cards.
add_filter( 'depositline_applies', function ( $applies, $product ) {
	return $product->is_type( 'gift-card' ) ? false : $applies;
}, 10, 2 );
```

## Balances

| Hook | What it's for |
|---|---|
| `depositline_due_date` (filter) | The default due date of a balance (`$date, $order`): `$date` is `Y-m-d` in the store's time zone, `$order` the deposit order. Applied when the balance order is made (and on import), unless a date was set on the order. An invalid date is ignored. |
| `depositline_balance_created` (action) | A deposit order's balance order was made (`$balance, $order`: the balance order, then the deposit order). Fires when the deposit is paid, or when an open balance is imported. |
| `depositline_balance_paid` (action) | A balance was paid and the deposit order moved on to Processing or Completed (`$parent, $balance`: the deposit order, then the balance order). Also fires when Depositline is activated again, or a conflicting plugin is gone, for balances paid in the meantime. |

```php
// Balances are due on the 1st of the month after the usual due date.
add_filter( 'depositline_due_date', function ( $date, $order ) {
	return ( new DateTime( $date ) )->modify( 'first day of next month' )->format( 'Y-m-d' );
}, 10, 2 );

// Tell the warehouse when a layaway is fully paid.
add_action( 'depositline_balance_paid', function ( $parent, $balance ) {
	wp_mail( 'warehouse@example.com', 'Paid in full: order #' . $parent->get_order_number(), 'Ready to ship.' );
}, 10, 2 );
```

## Charging saved cards

| Hook | What it's for |
|---|---|
| `depositline_charge_connectors` (filter) | Connectors that charge saved cards for balances (`$connectors`, an array of `Extendiment\Depositline\Charging\Connector`). The built-in Stripe connector is there when the WooCommerce Stripe Gateway is active. Anything that isn't a `Connector` is dropped. |

A connector implements two methods:

- `gateway_id(): string`: the WooCommerce payment gateway whose saved cards (payment tokens) it charges. The gateway must be enabled.
- `charge( WC_Order $order, WC_Payment_Token $token ): array`: charge the balance order's total off-session (the customer isn't there). Return `result` (`"paid"` or `"failed"`), optionally `transaction` (the transaction ID, passed to `payment_complete()`) and `message` (why it failed, in words the customer can read: it goes into their email). A thrown exception counts as a failure.

On `"paid"`, Depositline sets the balance order's payment method to that gateway and completes it. On `"failed"`, the customer gets the payment link with the message.

```php
use Extendiment\Depositline\Charging\Connector;

class My_Gateway_Connector implements Connector {
	public function gateway_id(): string {
		return 'my_gateway';
	}
	public function charge( WC_Order $order, WC_Payment_Token $token ): array {
		$response = my_gateway_charge( $token->get_token(), $order->get_total(), $order->get_currency() );
		return $response->ok
			? array( 'result' => 'paid', 'transaction' => $response->id )
			: array( 'result' => 'failed', 'message' => 'Your card was declined.' );
	}
}

add_filter( 'depositline_charge_connectors', function ( $connectors ) {
	$connectors[] = new My_Gateway_Connector();
	return $connectors;
} );
```

## Other deposits plugins

| Hook | What it's for |
|---|---|
| `depositline_conflicts` (filter) | The active plugins Depositline won't run beside (`$names`, plugin file => name). Depositline pauses while the list isn't empty. By default: WooCommerce Deposits, Deposits & Partial Payments for WooCommerce and YITH WooCommerce Deposits / Down Payments, when active. |

```php
// Pause Depositline while our own deposits plugin is active.
add_filter( 'depositline_conflicts', function ( $names ) {
	if ( is_plugin_active( 'my-deposits/my-deposits.php' ) ) {
		$names['my-deposits/my-deposits.php'] = 'My Deposits';
	}
	return $names;
} );
```

## Settings page

| Hook | What it's for |
|---|---|
| `depositline_settings` (action) | Depositline's sections and fields have been added to its settings page (`$page`, the slug `depositline`), on `admin_init`. Add your own with `add_settings_section()` / `add_settings_field()` on that page, and register options in the `depositline` group. |

```php
add_action( 'depositline_settings', function ( $page ) {
	register_setting( 'depositline', 'my_layaway_terms' );
	add_settings_section( 'my_layaway', 'Layaway terms', '__return_false', $page );
	add_settings_field( 'my_layaway_terms', 'Terms page', function () {
		wp_dropdown_pages( array( 'name' => 'my_layaway_terms', 'selected' => (int) get_option( 'my_layaway_terms' ), 'show_option_none' => '—' ) );
	}, $page, 'my_layaway' );
} );
```

## Store API (Checkout block)

- **Cart extension data**, namespace `depositline` (`cart.extensions.depositline`): `deposit` (a deposit is paid today), `optional` (the customer may pay in full), `plan` (`deposit` or `full`), `later` (the balance), `moved` (tax paid today because the balance can't carry it, `0` when none), `note` (that note's text, or empty), `card_offered` (the saved-card checkbox applies).
- **Cart update**, namespace `depositline`: `extensionCartUpdate( { namespace: 'depositline', data: { plan: 'full' } } )` switches optional deposits to paying in full; `deposit` switches back.
- **Checkout extension data**, `depositline.balance_card` (boolean): the customer agrees to have the balance charged to a saved card.

## WP-CLI

- `wp depositline import [--dry-run]`: imports WooCommerce Deposits or Webtomizer product settings and open balances; `--dry-run` only says what would be imported. Fails while another deposits plugin is active.
- `wp depositline remind <balance-order>`: runs a balance order's next step now (the reminder, the due-date charge or link, an overdue reminder, or the overdue action) and schedules the one after.

## Constants

`DEPOSITLINE_VERSION`, `DEPOSITLINE_FILE`, `DEPOSITLINE_URL` and `DEPOSITLINE_DIR`.

Source: https://extendiment.com/plugins/depositline/docs/1.x/hooks