CartThrob Gift Certificates Version 5.1.0
Overview
CartThrob Gift Certificates adds gift-certificate purchase and redemption flows on top of CartThrob checkout.
Core outcomes:
- sell gift certificates through checkout
- redeem gift codes into active session balance
- apply gift balances automatically during checkout
- track certificates and redemptions in Control Panel
- notify gift recipients when purchased as a gift
Requirements
- CartThrob Gift Certificates
5.1.0 - CartThrob installed and active
- PHP
>= 7.1(fromcomposer.json) - Stripe and PayPal gift certificate support requires CartThrob Gift Certificates
5.1.0+and CartThrob10+ - Changelog support targets:
5.0.0adds ExpressionEngine 7 + CartThrob 7 + PHP 8 support;4.0.0adds ExpressionEngine 6 + CartThrob 6 support
Installation
Bundled path:
/system/user/addons/cartthrob_gift_certificates/
Install in ExpressionEngine:
- Go to
Add-ons. - Install
CartThrob Gift Certificates. - Run add-on updates if prompted.
Installer creates:
- module + extension + action (
add_gift_certificate_action) - notification event (
gift_certificate_purchased_as_gift) - tables:
cartthrob_gift_certificates,cartthrob_gift_certificates_redemptions,cartthrob_gift_certificates_settings
Upgrading
- Deploy updated files to
/system/user/addons/cartthrob_gift_certificates/. - Run the Gift Certificates add-on update in ExpressionEngine. This step is required for 5.1.0: it registers the CartThrob 10 checkout-quote hook and resynchronizes the add-on’s other extension hooks.
- Verify:
- Gift Certificates list loads
- Redemptions list loads
- settings save successfully
- checkout purchase/redeem flow still works in staging
No checkout-template change is required for payment gateways to receive the reduced amount. CartThrob 10 sites should nevertheless show the adjustment to the customer and enable price-change review, as described below.
Start Here (10-Minute Setup)
Goal: create one certificate flow end-to-end.
- In Control Panel, set
gift_certificate_code_lengthin Gift Certificates settings. - Add a purchase form using
exp:cartthrob:add_to_cart_formwithgift_certificate="yes". - Add optional form inputs:
gift_certificate_noteandgift_certificate_email_address. - Add a redemption form using
exp:cartthrob:redeem_gift_certificate_formwith an input namedgift_certificate_code. - Place an order for a gift certificate and redeem it in a test session.
When testing Stripe or PayPal, use CartThrob Gift Certificates 5.1.0 or newer with CartThrob 10 or newer.
Common Tasks With Examples
1. Sell a Gift Certificate in Checkout
{exp:cartthrob:add_to_cart_form
on_the_fly="yes"
price="20"
return="store/checkout"
tax_exempt="yes"
shipping_exempt="yes"
gift_certificate="yes"
}
<input type="text" name="gift_certificate_note" value="" />
<input type="text" name="gift_certificate_email_address" value="" />
<button type="submit">Add Gift Certificate</button>
{/exp:cartthrob:add_to_cart_form}
2. Redeem a Gift Code
Stripe and PayPal: Applying a gift certificate to these checkouts requires CartThrob Gift Certificates 5.1.0 or newer and CartThrob 10 or newer.
{exp:cartthrob:redeem_gift_certificate_form return="gift_certificates/info"}
<input type="text" name="gift_certificate_code" value="" />
<button type="submit">Redeem</button>
{/exp:cartthrob:redeem_gift_certificate_form}
3. Show Gift Balance in Cart/Checkout
Stripe and PayPal: Applying a gift certificate to these checkouts requires CartThrob Gift Certificates 5.1.0 or newer and CartThrob 10 or newer.
Applied: {exp:cartthrob:applied}
Remaining Gift Balance: {exp:cartthrob:balance}
Net Cart Total: {exp:cartthrob:cart_total_minus_gift_certificates}
Numeric variants:
{exp:cartthrob:applied:numeric}{exp:cartthrob:balance:numeric}{exp:cartthrob:cart_total_minus_gift_certificates:numeric}
Empty carts still return numeric 0 from the :numeric variants. Those tags also load CartThrob’s number library without mutating cart metadata.
Gift certificates reduce the amount due at payment time; they do not replace CartThrob’s original cart total. A checkout can show the calculation explicitly:
<p>Order total: {exp:cartthrob:cart_total}</p>
<p>Gift certificate applied: -{exp:cartthrob:applied}</p>
<p>Amount due: {exp:cartthrob:cart_total_minus_gift_certificates}</p>
On CartThrob 10, set price_change_handling="review" on the checkout form so CartThrob displays its review step if the finalized server quote differs from the amount initially shown:
{exp:cartthrob:checkout_form
return="store/order_complete"
price_change_handling="review"
}
<!-- checkout fields -->
{/exp:cartthrob:checkout_form}
The add-on supplies the gift-certificate adjustment to CartThrob’s server-authoritative quote. It does not inject checkout markup automatically.
4. Show Current Member Purchase History
{exp:cartthrob:gift_certificates_data}
{gift_certificate_code} - {amount} - {status}
{if no_results}
No gift certificates purchased.
{/if}
{/exp:cartthrob:gift_certificates_data}
Quick Links For Existing Users
- Need to issue or adjust a certificate manually: see
Create Gift CertificateandEdit Gift Certificate. - Need audit trail of use: see
Redemptions. - Need output for cart item gift metadata: see
gift_certificates_infotag. - Need checkout math values: see
applied,balance,cart_total_minus_gift_certificatestags.
Control Panel Reference
Gift Certificates List (addons/settings/cartthrob_gift_certificates)
Table Columns
ID
- gift certificate ID - click opens edit screen
Purchaser
- purchaser screen name and member ID when available
- click opens member profile
- shows Guest when no relation exists
Balance
- remaining certificate balance (currency formatted)
Amount
- original purchased amount (currency formatted)
Created Date
- creation timestamp formatted using site/user date format
Status
- status badge (open, closed, redeemed, processing)
Manage
- edit icon opens edit screen - remove icon opens delete confirmation
Create Gift Certificate (.../gift-certificate/add)
Form fields:
member_id(required text)amount(text)gift_certificate_note(textarea)gift_certificate_email_address(text)status(select:open,closed,redeemed,processing)
Behavior:
gift_certificate_codeis auto-generated- generated codes are unique and use the configured length; the setting accepts values from
16through255 timestampis set at create time- model validation requires a valid member, amount greater than
0and less than1000000, status, code, and timestamp - email, when provided, must be a valid address
- on insert,
balanceis auto-set toamount - on insert, gift notification logic runs
Edit Gift Certificate (.../gift-certificate/edit/{id})
Read-only info blocks:
- code
- member link
- order link
- created date
Editable fields:
statusamountbalancegift_certificate_notegift_certificate_email_address
Behavior:
- saves directly to certificate model after validation
amountmust be greater than0and less than1000000balanceis required and must be a number between0and the certificate amount- email, when provided, must be a valid address
Delete Gift Certificate (.../gift-certificate/delete/{id})
Shown context:
- code
- member link
Delete field:
confirm(yes/no)
Behavior:
- deletes only when
confirm = y
Redemptions (.../redemptions)
Table Columns
IDMember Info
- linked member profile when available, otherwise Guest
Amount
- redemption amount
Balance
- remaining balance at redemption time
Order ID
- links to order entry editor
Redemption DateStatus
Settings (.../settings)
Fields:
order_channel_gift_certificates_field(select)
- shown only when CartThrob save_orders and orders_channel are configured
- stores redeemed gift codes into selected order-channel field
- may be cleared; a submitted value must belong to the configured order channel
gift_certificate_code_length(text)
- controls auto-generated code length
- valid range is 16–255
- blank values return to the default of 32
Template Installation (.../install)
The Installation screen lists bundled template groups that are available but not yet installed. Select the desired group and submit the form to install its example Gift Certificates templates. Existing template groups are not offered for installation again.
Notifications
Event registered:
gift_certificate_purchased_as_gift
Notification send behavior:
- sent when gift certificate record is inserted
- sent only when recipient email differs from purchaser session email
- email constants populated:
{gift_certificate_code},{gift_certificate_note},{gift_certificate_amount},{gift_certificate_email_address}
Template Tags
Tag namespace in current templates: exp:cartthrob:<tag_name>.
Legacy docs may show exp:cartthrob_gift_certificates:<tag_name> syntax, but this codebase’s installer templates and tag classes use exp:cartthrob:<tag_name>.
balance
Returns remaining redeemable gift balance from active cart-applied gift codes after current cart total is considered.
Parameters:
- numeric modifier supported via tag suffix:
:numeric
Examples:
{exp:cartthrob:balance}
{exp:cartthrob:balance:numeric}
applied
Returns gift amount currently applied to this cart total.
Parameters:
- numeric modifier supported via tag suffix:
:numeric
Examples:
{exp:cartthrob:applied}
{exp:cartthrob:applied:numeric}
cart_total_minus_gift_certificates
Returns cart total after open gift certificate balances are applied.
Parameters:
- numeric modifier supported via tag suffix:
:numeric
Examples:
{exp:cartthrob:cart_total_minus_gift_certificates}
{exp:cartthrob:cart_total_minus_gift_certificates:numeric}
total_gift_certificates
Returns the sum of the original amounts of all open gift certificates owned by a member. It does not subtract previous redemptions or report the certificates’ remaining balances.
Parameters:
member_id
- optional
- supports CURRENT_USER, {logged_in_member_id}, {member_id}
- defaults to current session member
- numeric modifier supported via tag suffix:
:numeric
Examples:
{exp:cartthrob:total_gift_certificates}
{exp:cartthrob:total_gift_certificates member_id="CURRENT_USER"}
{exp:cartthrob:total_gift_certificates:numeric}
active_gift_certificates
Pair tag. Returns currently active gift certificates in cart session metadata.
Parameters:
- none
Variables:
{id}{member_id}{gift_certificate_email_address}{gift_certificate_note}{gift_certificate_code}{order_id}{timestamp}{expires}{status}{description}{balance}{balance:numeric}{amount}{amount:numeric}
Conditionals:
{if no_results}when no active certificate rows are found
gift_certificates_data
Pair tag. Returns purchased certificate data by order_id or member.
Parameters:
order_id
- when provided, query is order-specific
member_id
- used when order_id is not provided
- supports CURRENT_USER, {logged_in_member_id}, {member_id}
order_by
- sort field, default id
- applied ascending in current implementation
limit
- default 100
offset
- default 0
Variables:
- same certificate fields as
active_gift_certificates - includes formatted + numeric variants for
amountandbalance
Conditionals:
{if no_results}
redemptions
Pair tag. Returns redemption rows with status open, filtered by order_id or member.
Parameters:
order_idmember_id
- used when order_id is omitted
- supports CURRENT_USER, {logged_in_member_id}, {member_id}
Variables:
{id}{certificate_id}{member_id}{order_id}{timestamp}{amount}{amount:numeric}{balance}{balance:numeric}{status}{cart_id}
Conditionals:
{if no_results}
gift_certificates_info
Pair/single-row helper tag for cart-item metadata.
Parameters:
row_id(required)
- cart row ID from cart items loop
Conditionals:
{if is_gift_certificate}
Variables:
{gift_certificate_email_address}{gift_certificate_note}{gift_certificate_amount}{gift_certificate_amount:numeric}
redeem_gift_certificate_form
Form tag for submitting gift code redemption.
Parameters:
- standard form-builder passthrough parameters
- explicitly handled form-data keys:
action,secure_return,return,language - boolean encoding support:
json
Required input field inside form:
gift_certificate_code
Example:
{exp:cartthrob:redeem_gift_certificate_form return="gift_certificates/info"}
<input type="text" name="gift_certificate_code" value="" />
<button type="submit">Redeem</button>
{/exp:cartthrob:redeem_gift_certificate_form}
Gift Certificate Checkout Integration
Gift certificate purchase is implemented by extending CartThrob core add-to-cart behavior.
Stripe and PayPal: Applying a gift certificate to these checkouts requires CartThrob Gift Certificates 5.1.0 or newer and CartThrob 10 or newer.
Behavior:
- form-start hook injects an encrypted gift-certificate marker (
GFC) bound to that form’s identity - add-to-cart hook marks item metadata as a gift certificate only when the authenticated marker matches the submitted form hash (
FRM) - a marker copied onto a different add-to-cart form is ignored
- legacy unbound and malformed markers are rejected
- the
gift_certificate="yes"API is unchanged, including on-the-fly forms - authorize hook creates gift certificate records for matching purchased items
Security and Processing Model
During CartThrob 10 checkout quotes:
- applied gift certificates reduce the quoted total
- quote processing stops if any applied certificate is no longer available
During checkout pre-process:
- active gift codes are loaded from cart session metadata
- checkout stops with
ct.gc.gift_certificate_unavailableif an applied certificate is missing, closed, or otherwise unavailable - remaining balances are reserved inside one database transaction
- redemption rows are created in the same transaction with status
processing - if any reservation fails, the complete set is rolled back; with CartThrob 10, checkout stops before the payment provider is contacted, but older Stripe checkout paths may contact Stripe first
- each redemption records that certificate’s actual contribution
On authorize success:
- redemption rows move to
open - certificates become
redeemedwhen balance reaches zero, otherwiseopen - cart gift metadata is cleared
On fail/decline:
- processing redemptions are removed
- certificate balances and status are restored (
open)
Changelog
Version 5.1.0
Release October 20, 2026
- UPDATED: Control Panel code to use current CartThrob routes and navigation.
- UPDATED: Control Panel form field validation.
- UPDATED: Date formatting within Control Panel views.
- UPDATED: Gift certificate code generation to require unique codes between 16 and 255 characters.
- UPDATED: Form security for gift certificate purchases.
- FIXED: Stripe and PayPal checkouts now accurately reflect payments with gift certificates applied. Requires CartThrob 10.
- FIXED: Gift certificate purchase timestamps.
- FIXED: Email notification compatibility.
- FIXED: Redeemed gift certificate codes were not saved to the configured order field on newer CartThrob versions.
- FIXED: PHP 8.1 compatibility.
- FIXED: Template tag number formatting when tags are used alone.
- FIXED: Case-sensitive hook filenames.
- FIXED: Uninstall cleanup for ExpressionEngine member groups and roles.
- FIXED: Extension hooks not being fully registered during updates.
- FIXED: Numeric applied and balance tags on empty carts.
- FIXED: The Order Channel Gift Certificates Field could not be cleared, and leaving Gift Certificate Code Length blank did not reset it to 32.
- FIXED: Multiple gift certificates recording incorrect redemption amounts.
- FIXED: Certificate balance race condition with simultaneous checkouts.
- FIXED: Checkout could continue at full price when a gift certificate became unavailable. It now shows an error.
Version 5.0.0
Released September 19, 2022
- ADDED: ExpressionEngine 7 + CartThrob 7 support.
- ADDED: PHP 8 support.
Version 4.0.0
Released January 10, 2022
- ADDED: ExpressionEngine 6 + CartThrob 6 support.
- ADDED: Seeder support for Gift Certificate and Redemption test data.
- UPDATED: Control Panel view for improved readability.
- FIXED: Math error in
cart_total_minus_gift_certificates. - FIXED: Logic error related to
cart_total_minus_gift_certificates.
Version 3.0.1
Released January 08, 2021
- UPDATED: Exception handling when calling undefined module methods.
- FIXED: MySQL 5.6 support in updater column migration.
- FIXED: Undefined index notice when sending gift certificate purchase notifications.