# Hooks - Giftline 1.x documentation

> Giftline's functions for other plugins, its actions and filters, the REST routes and the WP-CLI commands.

Put the examples in a small custom plugin or your child theme's `functions.php`. Giftline's classes live in the `Extendiment\Giftline` namespace.

Amounts you pass are decimals in the store currency (`12.50`). Amounts in hooks are integers in minor units (cents): `Extendiment\Giftline\Money::from_minor( $minor )` turns them into an amount. A balance (`$account` below) is an object with `id`, `kind` (`card` or `credit`), `code` (cards), `user_id`, `email`, `balance` and `initial` (minor units), `currency`, `status` (`active`, `disabled`, `expired`), `expires_at` (UTC), `order_id`, `physical`, `recipient_name`, `recipient_email`, `sender_name`, `message` and `design`.

## Functions

Check for them with `function_exists( 'giftline_add_credit' )`: they're defined once Giftline has loaded with WooCommerce active. A customer is a user ID, a `WP_User`, a `WC_Customer` or an email address. Every write takes an optional `key` in `$args`: calling again with the same key returns the first result and does nothing else (no balance change, no action and no email), so retries are safe. Use one per business event, such as `myreturns:return:123`.

| Function | Returns | |
|---|---|---|
| `giftline_add_credit( $customer, $amount, $source = 'api', $reference = '', $args = [] )` | ledger entry ID or `WP_Error` | Adds store credit. `$source` is a short key for your plugin, `$reference` your own ID. `$args`: `note`, `key`, `order_id`, `notify` (send the Store credit received email, default `true`), `guest` (`true` with an email address: keep the credit for that address even when an account has it, as refunds of guest orders do), `type` (`'refund'` for an order refund paid as store credit, shown as "Refund to credit" in the history; default `'issue'`, credit granted). An email address without an account gets credit kept for that address, which the customer adds to an account from an emailed link. |
| `giftline_deduct_credit( $customer, $amount, $source = 'api', $reference = '', $args = [] )` | ledger entry ID or `WP_Error` | Takes store credit away, never below zero (`giftline_insufficient`). `$args`: `note`, `key`, `order_id`, `guest` (`true` with an email address: the credit kept for that address, even when an account has it). |
| `giftline_get_credit( $customer, $args = [] )` | `float` | The customer's spendable credit; 0 when there's none or it's disabled. `$args`: `guest` (`true` with an email address: the credit kept for that address, even when an account has it). |
| `giftline_issue_card( $amount, $args = [] )` | `[ 'id' => int, 'code' => string ]` or `WP_Error` | Creates a gift card. `$args`: `recipient_email`, `recipient_name`, `sender_name`, `message`, `design`, `expires` (`Y-m-d`; left out: from the settings; `''`: none), `code` (your own), `physical`, `send` (email it now; default `true` when there's a recipient email), `note`, `source`, `key`. |
| `giftline_get_card_balance( $code )` | `float` or `null` | A card's balance by its code (any case, dashes optional). It isn't rate-limited: don't expose it to visitors yourself. |
| `giftline_refund_to_credit( $order, $amount, $args = [] )` | `WC_Order_Refund` or `WP_Error` | Refunds an order to store credit, as the order screen's button does: a WooCommerce refund for the amount without the payment gateway, plus the same amount of credit for the order's customer (or its billing email for a guest order). `$args`: `reason`, `line_items` and `restock_items` (as for `wc_create_refund()`), `notify`. Don't also create a refund of your own. |

The same calls are static methods of `Extendiment\Giftline\Api`: `add_credit()`, `deduct_credit()`, `get_credit()`, `issue_card()`, `get_card_balance()` and `refund_to_credit()`.

```php
// A returns plugin paying a return as store credit, safe to run twice.
if ( function_exists( 'giftline_add_credit' ) ) {
	$customer = $order->get_customer_id() ? $order->get_customer_id() : $order->get_billing_email();
	$entry    = giftline_add_credit( $customer, $amount, 'myreturns', (string) $return_id, array(
		'key'      => 'myreturns:return:' . $return_id,
		'order_id' => $order->get_id(),
	) );
}
```

## Actions

| Action | When |
|---|---|
| `giftline_loaded` | Giftline has loaded (on `plugins_loaded`, with WooCommerce active). Its classes, `GIFTLINE_*` constants and `giftline_*` functions are available. |
| `giftline_settings` | The settings page is being built (`$page`, the page slug `giftline`): add your own sections and fields with the Settings API. |
| `giftline_ledger_entry` | Any balance changed (`$entry_id, $account, $amount, $type, $args, $balance_after`). `$account` is as it was before the change; `$type` is `issue`, `redeem`, `restore`, `refund`, `adjust`, `expire` or `revoke`; `$args` has `source`, `reference`, `order_id`, `note`, `user_id` and `key`. |
| `giftline_credit_added` | Store credit was added by staff, a refund, an import or the API (`$entry_id, $account, $minor, $args`). `$args` has what the caller passed, with `source` and `reference`. |
| `giftline_card_issued` | A gift card was created: bought, by staff, imported or through the API (`$account`). |
| `giftline_redeemed` | An order spent gift cards or store credit (`$order, $plan`). Each line of `$plan` has `account` (ID), `amount` (minor units), `kind` and `label`. |
| `giftline_send_pdf` | Printable cards are about to be sent as a PDF, to staff printing or a customer printing their own card (`$name, $accounts`: the file name and the cards). |

```php
// Tell a CRM when a customer gets store credit.
add_action( 'giftline_credit_added', function ( $entry_id, $account, $minor ) {
	my_crm_note( $account->user_id, sprintf( 'Store credit +%s', \Extendiment\Giftline\Money::from_minor( $minor ) ) );
}, 10, 3 );
```

## Filters

| Filter | What it's for |
|---|---|
| `giftline_redemption_plan` | Which balances pay for the cart and how much (`$plan, $cart`). Same lines as `giftline_redeemed`. By default the applied cards in order, then store credit, each up to what's left after the gift card lines. |
| `giftline_lookup_allowed` | Whether a visitor may look up a gift card code now (`$ok`), at checkout and in the balance check. `$ok` is false once they've typed too many wrong codes this hour. A CAPTCHA plugin can return false until its challenge is passed. |
| `giftline_client_ip` | The IP address wrong codes are counted against (`$ip`, the connection's own address). Behind a reverse proxy or CDN that every request passes through, return the visitor's address it passes on. See [Wrong codes and security](wrong-codes-and-security). |
| `giftline_code_length` | The length of new codes, 12 to 32 characters (default 16). |
| `giftline_price_html` | A gift card product's price (`$html, $product`), such as "$25.00 – $100.00". |

```php
// Shorter codes for cards printed on small tickets.
add_filter( 'giftline_code_length', function () {
	return 12;
} );
```

## REST API

Routes under `/wp-json/giftline/v1`:

| Route | Who | |
|---|---|---|
| `GET /balance?code=…` | Anyone | A card's balance. Wrong codes count towards the visitor's limit (404, then 429). |
| `GET /customers/<id>/credit` | Staff, or that customer | A customer's store credit. |
| `POST /credit` | Staff | Adds credit: `customer` (user ID) or `email`, `amount`, `source`, `reference`, `note`, `key`, `notify`. |
| `POST /cards` | Staff | Creates a card: `amount`, `email`, `name`, `message`, `expires`, `key`, `send`. |

Staff means a user who can manage WooCommerce, authenticated as for WooCommerce's own REST API (an application password, for example).

## WP-CLI

| Command | |
|---|---|
| `wp giftline balance <code\|user\|email>` | A card's or a customer's balance. |
| `wp giftline credit <user\|email> <amount> [--note=<note>] [--notify]` | Adds store credit; a negative amount takes it away. |
| `wp giftline issue <amount> [--count=<n>] [--email=<email>] [--expires=<Y-m-d>]` | Creates one card or a batch, and prints the codes. |
| `wp giftline verify` | Checks that every balance equals the sum of its history. |
| `wp giftline daily` | Runs the daily job now: expiry, reminders and history clean-up. |

## Emails and templates

The emails are WooCommerce emails with the IDs `giftline_gift_card`, `giftline_credit`, `giftline_expiry` and `giftline_low_balance`. Their templates are in `templates/emails/` (and `templates/emails/plain/`); copy one to `your-theme/woocommerce/emails/` to change it.

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