Three rules shape this plugin. Each one is there because the common way of doing gift wrap gets it wrong.
Rule 1: gift wrap is a fee, not a product
The usual shortcut is to create a "Gift wrap" product and put it in the cart. That one move breaks your stock report, your product feed, your sales-by-product figures and any per-item shipping rule, and it puts "Gift wrap" into "customers also bought".
Gatemi Gift Wrap adds the charge with WooCommerce's own WC_Cart::add_fee(). A fee:
- is shown by the classic cart, the Cart and Checkout blocks, the Store API and every email, without any template of this plugin's;
- lands on the order as a fee line, where an accountant expects it;
- can be taxed (full edition) like any other WooCommerce fee.
Rule 2: the charge is worked out again on every pass
WooCommerce recalculates a cart many times — every quantity change, every coupon, every shipping change. It clears its fees each time and asks every plugin again on woocommerce_cart_calculate_fees.
Gatemi Gift Wrap answers from two things only: whether the shopper ticked the box (kept in the WooCommerce session) and the price in your settings (and, in the full edition, the cart's item count). It never stores an amount between passes. So:
- the fee cannot double when the cart is updated twice;
- it disappears the moment the box is unticked;
- if you change the price, the next recalculation uses the new price.
Full edition, per-item charging. With For each thing in the cart chosen, the fee is the price times the cart's item count (get_cart_contents_count()). Example: price 2.00, a cart with two mugs and one scarf is 3 items, so the fee is 6.00. Remove a mug and it becomes 4.00 on the next recalculation.
Rule 3: the person packing the box is the audience
A gift message only the customer sees is a parcel that ships with no card in it. So the gift is shown:
- in a Gift box in the sidebar of the order screen — on both the HPOS orders screen and the classic one, and only on orders that actually have a gift, so the box means something when it appears;
- in every order email, the admin's new-order email included (it rides
woocommerce_email_order_details, which every order email fires); - on the order-received page and the order view in My Account.
Plain-text emails get plain text ("Gift wrapping: yes", then the message) rather than markup, because a lot of warehouses print those.
The message keeps its line breaks — a card is written in lines — and loses any HTML. It is stripped again when it is read back, so a message restored from a backup cannot reach a packing slip as markup.
The flow on the classic cart and checkout
- The cart page shows the gift box just above the order total (
woocommerce_cart_totals_before_order_total). - The shopper ticks the box and clicks Update cart. The choice rides WooCommerce's own cart update and is saved in the session.
- On the classic checkout the box appears above the order notes. Ticking it triggers the checkout's own review refresh, so the fee appears in the totals without a page reload.
- When the order is created, the plugin writes
_gmgw_wrap=yesand_gmgw_messageonto it through the order's own meta API (so HPOS and the legacy order store behave the same). - After the order is placed — or if the cart is emptied — the choice is forgotten. Otherwise the shopper's next, ordinary order would arrive gift-wrapped with last week's birthday message.
The form needs no JavaScript and has no endpoint of its own: it posts with WooCommerce's own forms. That is why it keeps working behind a page cache.
The flow on the Cart and Checkout blocks
The block cart and checkout — a new store's default — fire none of the classic hooks. Rather than build a second checkout, the plugin hands its two fields to WooCommerce's Additional Checkout Fields API (WooCommerce 8.9 or later):
- The checkout block's Order information step shows a checkbox (your tick-box label, or "Wrap it as a gift") and, if messages are on, a Gift message text field.
- As the shopper edits the checkout, the block sends its fields to the Store API. The plugin copies them into the same session the classic path uses, so the same fee code adds the charge.
- When the order is placed, the plugin reads the fields back off the order and writes the same
_gmgw_wrapand_gmgw_messagekeys.
Two differences from the classic surfaces, both caused by how WooCommerce's API works:
- The block cart page has no tick box. The choice is made on the block checkout.
- On the block checkout the fee follows the tick a moment behind the shopper, after the block's next update, rather than instantly. It always lands correctly on the placed order.
On a WooCommerce older than 8.9 the block checkout simply shows no gift fields; the classic pages are unaffected.
When two editions are installed
If the full edition is active, the free edition does nothing. Both use the same fee hook and the same order keys, and two of them running would add two fees to one order.
