CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

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 (from composer.json)
  • Stripe and PayPal gift certificate support requires CartThrob Gift Certificates 5.1.0+ and CartThrob 10+
  • Changelog support targets: 5.0.0 adds ExpressionEngine 7 + CartThrob 7 + PHP 8 support; 4.0.0 adds ExpressionEngine 6 + CartThrob 6 support

Installation

Bundled path:

/system/user/addons/cartthrob_gift_certificates/

Install in ExpressionEngine:

  1. Go to Add-ons.
  2. Install CartThrob Gift Certificates.
  3. 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

  1. Deploy updated files to /system/user/addons/cartthrob_gift_certificates/.
  2. 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.
  3. 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.

  1. In Control Panel, set gift_certificate_code_length in Gift Certificates settings.
  2. Add a purchase form using exp:cartthrob:add_to_cart_form with gift_certificate="yes".
  3. Add optional form inputs: gift_certificate_note and gift_certificate_email_address.
  4. Add a redemption form using exp:cartthrob:redeem_gift_certificate_form with an input named gift_certificate_code.
  5. 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}
  • Need to issue or adjust a certificate manually: see Create Gift Certificate and Edit Gift Certificate.
  • Need audit trail of use: see Redemptions.
  • Need output for cart item gift metadata: see gift_certificates_info tag.
  • Need checkout math values: see applied, balance, cart_total_minus_gift_certificates tags.

Control Panel Reference

Gift Certificates List (addons/settings/cartthrob_gift_certificates)

Table Columns

  1. ID

- gift certificate ID - click opens edit screen

  1. Purchaser

- purchaser screen name and member ID when available - click opens member profile - shows Guest when no relation exists

  1. Balance

- remaining certificate balance (currency formatted)

  1. Amount

- original purchased amount (currency formatted)

  1. Created Date

- creation timestamp formatted using site/user date format

  1. Status

- status badge (open, closed, redeemed, processing)

  1. Manage

- edit icon opens edit screen - remove icon opens delete confirmation

Create Gift Certificate (.../gift-certificate/add)

Form fields:

  1. member_id (required text)
  2. amount (text)
  3. gift_certificate_note (textarea)
  4. gift_certificate_email_address (text)
  5. status (select: open, closed, redeemed, processing)

Behavior:

  • gift_certificate_code is auto-generated
  • generated codes are unique and use the configured length; the setting accepts values from 16 through 255
  • timestamp is set at create time
  • model validation requires a valid member, amount greater than 0 and less than 1000000, status, code, and timestamp
  • email, when provided, must be a valid address
  • on insert, balance is auto-set to amount
  • 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:

  1. status
  2. amount
  3. balance
  4. gift_certificate_note
  5. gift_certificate_email_address

Behavior:

  • saves directly to certificate model after validation
  • amount must be greater than 0 and less than 1000000
  • balance is required and must be a number between 0 and 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:

  1. confirm (yes/no)

Behavior:

  • deletes only when confirm = y

Redemptions (.../redemptions)

Table Columns

  1. ID
  2. Member Info

- linked member profile when available, otherwise Guest

  1. Amount

- redemption amount

  1. Balance

- remaining balance at redemption time

  1. Order ID

- links to order entry editor

  1. Redemption Date
  2. Status

Settings (.../settings)

Fields:

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

  1. 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:

  1. member_id

- optional - supports CURRENT_USER, {logged_in_member_id}, {member_id} - defaults to current session member

  1. 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:

  1. order_id

- when provided, query is order-specific

  1. member_id

- used when order_id is not provided - supports CURRENT_USER, {logged_in_member_id}, {member_id}

  1. order_by

- sort field, default id - applied ascending in current implementation

  1. limit

- default 100

  1. offset

- default 0

Variables:

  • same certificate fields as active_gift_certificates
  • includes formatted + numeric variants for amount and balance

Conditionals:

  • {if no_results}

redemptions

Pair tag. Returns redemption rows with status open, filtered by order_id or member.

Parameters:

  1. order_id
  2. member_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:

  1. 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_unavailable if 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 redeemed when balance reaches zero, otherwise open
  • 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.