CartThrob Gift Certificates Version 5.0.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.0.0
• CartThrob installed and active
• PHP >= 7.1 (from composer.json)
• 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 add-on updates in ExpressionEngine.
3. Verify:

- Gift Certificates list loads - Redemptions list loads - settings save successfully - checkout purchase/redeem flow still works in staging

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.

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

{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

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}

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

2. Purchaser

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

3. Balance

- remaining certificate balance (currency formatted)

4. Amount

- original purchased amount (currency formatted)

5. Created Date

- creation timestamp formatted using site/user date format

6. Status

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

7. Manage

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

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

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
• timestamp is set at create time
• model validation requires valid member, amount, status, code, timestamp
• on insert, balance is auto-set to amount
• on insert, gift notification logic runs

Edit Gift Certificate (.../edit-gift-certificate/{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

Delete Gift Certificate (.../delete-gift-certificate/{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

3. Amount

- redemption amount

4. Balance

- remaining balance at redemption time

5. Order ID

- links to order entry editor

6. Redemption Date
7. 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

2. gift_certificate_code_length (text)

- controls auto-generated code length - default fallback is 32

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 total amount for open gift certificates owned by a member.

Parameters:

1. member_id

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

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

2. member_id

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

3. order_by

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

4. limit

- default 100

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

Use exp:cartthrob:add_to_cart_form with:

• gift_certificate="yes"

Optional inputs:

• gift_certificate_note
• gift_certificate_email_address

Behavior:

• form-start hook injects encrypted gift-certificate marker
• add-to-cart hook marks item metadata as gift certificate
• authorize hook creates gift certificate records for matching purchased items

Security and Processing Model

During checkout pre-process:

• active gift codes are loaded from cart session metadata
• redemption rows are created with status processing
• certificate balances are reduced and status set to processing

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