Configuration

All of Tipping’s settings live on one screen, WooCommerce → Tipping, and are stored in a single tipping_settings option (an array). The page sits under the WooCommerce submenu and is gated to the manage_woocommerce capability; saving goes through options.php with the same capability. There are five settings, grouped into General and Presets.

General

Enable tipping

The master switch, on by default. When off, the control never renders and no CSS or JavaScript is enqueued on the storefront, the checkout is untouched. Stored as enabled (boolean).

Label

The heading shown above the tip buttons, e.g. Add a tip or Support our shelter. Stored as label. Leave it blank and Tipping falls back to “Add a tip”. This same text is used as the fee label on the order, so it is what the customer sees on the totals line and in emails.

Description

Optional supporting text under the label, e.g. a short note that tipping is always optional. Stored as description. Leave it blank to render just the heading and buttons.

Presets

Preset type

How each preset value is interpreted. Stored as type, one of:

• Percentage of cart (percent, the default), each value is a whole percentage of the pre-tip items subtotal. A 5 preset adds 5% of the subtotal, so a larger order means a larger tip.
• Fixed amount (fixed), each value is a flat amount in your store currency, the same whatever the cart total.

Preset values

Comma-separated numbers, stored as the presets list. For percentages use whole numbers (5, 10, 15); for fixed amounts use currency values (2, 5, 10). On save the values are run through wc_format_decimal, rounded to two decimals, and filtered to positive numbers only, zero, negative and non-numeric entries are dropped. A maximum of eight presets is kept; the rest are ignored. Leave the field empty and the control is hidden until you add at least one.

The settings page renders a non-interactive preview of the resulting pills (percentages as 5%, fixed values formatted with wc_price) so you can see the effect before saving.

The “usable” rule

The control only appears when it is enabled and has at least one valid preset. If either is false, the storefront renders nothing, no assets load, and no fee is added, there is no broken or empty widget. This is why an enabled install with the presets field cleared simply hides the control.

How the tip is applied

• The customer’s choice (a preset index, or “none”) is stored in the WooCommerce session over a nonce-protected AJAX call (tipping_set).
• On every woocommerce_cart_calculate_fees, Tipping resolves the choice to an amount and adds it with WC_Cart::add_fee(). The fee is added non-taxable, tips and donations are not taxed, and this is not configurable.
• A percentage tip is computed from WC_Cart::get_subtotal() (the pre-tip, tax-exclusive items subtotal) at calculation time, so it tracks the live cart.
• An empty / “No tip” selection resolves to 0 and no fee line is added, there is never a £0 tip row.
• At checkout, the resolved amount is written to the order as _tipping_amount meta (woocommerce_checkout_create_order), for auditing alongside the fee.

What is fixed by design

A few behaviours are deliberately not settings:

• Tips are never taxed, the fee is always added as non-taxable.
• The default selection is always “No tip”, there is no setting to preselect a preset, which keeps tipping fully opt-in.
• The control renders only on the classic checkout, at woocommerce_review_order_before_payment. There is no placement setting and no cart-page rendering.
• There are no shortcodes, the control appears automatically on the checkout when usable, or not at all.

Template

The control is rendered from templates/tip-control.php inside the plugin. It is loaded directly from the plugin directory, there is no theme-override path, so copying it into your theme has no effect. Adjust the appearance with CSS (below) rather than by replacing the template.

Theming with CSS

The storefront styles are built on --tipping-* custom properties, accent, ink, border, pill background, radius and gap, so you can re-theme the control from your theme stylesheet:

.tipping {
    --tipping-accent: #0a7c66;   /* hover + active border, focus ring */
    --tipping-ink: #075c4b;      /* active text + the underline stroke */
    --tipping-radius: 8px;
}

The default accent is a warm honey-amber, and the chosen preset draws a hand-drawn “tip line” underline inside the pill (no layout shift). Dark-mode colours and a prefers-reduced-motion block (which disables the transitions) are built in and need no configuration. The accent falls back to your theme’s --wp--preset--color--primary where one is exposed.

Extending Tipping (developers)

Tipping exposes two merchant/dev-facing hooks.

tipping/fee_amount, filter the resolved tip amount before it becomes a cart fee. The selection service is passed so you can read the subtotal without recomputing it. This is the hook Pro round-up tipping uses:

add_filter( 'tipping/fee_amount', function ( float $amount, $selection ): float {
    // Round the order up to the next whole unit and tip the difference.
    $subtotal = $selection->cartSubtotal();
    $roundUp  = ceil( $subtotal ) - $subtotal;

    return $amount + $roundUp;
}, 10, 2 );

tipping/admin_after_cards, fires inside the settings form, after the free setting cards and before the submit button. Add-ons echo their own .tipping-admin__card here; fields named under tipping_settings[...] save with the form. The settings page/option-group slug is available as \Tipping\Admin\Settings::pageSlug() (tipping-settings) so add-ons can register settings against the same group.

Storage and cleanup

Settings live in the single tipping_settings option; a tipping_db_version option tracks the schema. Tipping creates no custom database tables. Deleting the plugin runs the uninstall routine, which removes both options but keeps any _tipping_amount order meta, that is part of completed orders’ financial record. Everything stays in your own database; Tipping contacts no external service.