Hooks

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().

// 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).

// 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.
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".

// 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.