CartThrob Gift Certificates

CartThrob Gift Certificates Version 1.23

CartThrob Gift Certificates addon enables your CartThrob powered site to sell gift certificates to members and allow members and guests alike to redeem gift certificates. Redemption of gift certificates does not require login or membership. Gift certificates can be purchased by members as gifts for others and later redeemed by guests.

CartThrob Gift Certificates is an addon for CartThrob. Like other CartThrob addons, it must be uploaded and installed on your website, and CartThrob must be active for it to run. To use this addon, you will need to add additional template tags for selling, redeeming, and viewing information about gift certificate balances. You can place the tags in any of your EE templates to suit your specific workflow. Sample template code can be found here in the documentation.

Features

  • Gift certificates can be gifted to other members and guests (with optional gift note included)

  • Gift certificate balances are stored in the database, and can be used across multiple transactions

  • Gift certificates can be used to make purchases in full, or in combination with another payment method (if gift amount only covers part of the purchase price)

  • Member can track current balance of all purchased gift certificates (including gifted certificates), and review information about specific gift certificates

  • Uses CartThrob's notification system to send emails when gift certificates are purchased for a friend

  • Gift certificate codes can be retrieved by the purchaser if lost.

  • Secure: Asynchronous checkouts or multiple redemptions of the same code are managed by locking each gift certificate during checkout. If two people try to redeem at the same time, only the first to checkout will be able to use the active gift certificate until the transaction completes.

Requirements

  • ExpressionEngine 2.5+ (not compatible with ExpressionEngine 3)
  • CartThrob 2.2+ (not compatible with CartThrob 3)
  • PHP 5.3+ (not compatible with PHP 7)

Installation

  • Upload the /system/expressionengine/third_party/cartthrob_gift_certificates/ folder to /system/expressionengine/third_party/
  • Make sure Extensions are enabled on your system
  • Install the CartThrob Gift Certificates module and extension (through EE's add-ons/modules panel)

Upgrading

  • Upload the /system/expressionengine/third_party/cartthrob_gift_certificates/ folder to /system/expressionengine/third_party/ Overwriting existing files.
  • Go to EE settings » addons » and click "Run Module Updates"

Settings

The settings are self-explanatory for the most part, however please pay note the default conversion rate. By default all gift certificate balances will be applied dollar for dollar. You can change this however, by adjusting the "default conversion rate". If you would like to allow the gift certificate user to be able to redeem 3 dollars for every 1 dollar of gift certificate balance, you would set this setting to "3". This feature is useful when your gift certificate is worth more or less than cash value, or if you offer purchase bonuses for gift certificate purchases.

Notifications

When CartThrob Gift Certificate addon is active, it adds additional notification options to CartThrob's notifications settings. Using CartThrob's notification settings you can specify a template that will be emailed to the receiver when a gift certificate is purchased as a gift. When you set up the email notification the "to" will be ignored, and replaced with the gift receiver's email address.

Purchasing Gift Certificates

You sell a gift certificate almost like you would any other product using CartThrob. The main difference is that you need to add gift certificate items to the cart using a special version of CartThrob's add_to_cart_form tag (documented below). To redeem Gift Certificates, your customer just needs to enter the certificate code in redeem_gift_certificate_form. From that point on during the user's current session the available balance will be applied towards any transaction until the entire balance is spent. Any left over certificate balance will be stored in the database, and can be accessed by the customer in a later session using the same gift code.

add_to_cart_form

This tag is used to output a form used by the customer to add a gift certificate to the cart. All parameters for this tag are the same as CartThrob's standard add_to_cart_form tag. The main difference, is that any time this form is used to add something to the cart, CartThrob will convert the purchased item to a gift certificate, and store the balance in the database when successfully purchased.

You can specify gift_certificate_note and gift_certificate_email_address form inputs if you'd like to allow the customer to gift the certificate to another person.

Note So that it's possible to retrieve balances at a later date if the gift code is lost, a gift certificate must be purchased by a logged in member. To redeem a gift code does not require a member account or login. It is possible to purchase gift certificates if the user is logged out, but the guest will not be able to access any information about this gift certificate in the future.
Example
{exp:cartthrob_gift_certificates:add_to_cart_form 
    return="" 
    on_the_fly="yes" 
    price="20"
    }
    Note
    <input type="text" value="" name="gift_certificate_note" /> 

    gift_certificate_email_address
    <input type="text" value="" name="gift_certificate_email_address" /> 

    <input type="submit" value="Add to Cart" />

{/exp:cartthrob_gift_certificates:add_to_cart_form}

Redeeming Gift Certificates

redeem_gift_certificate_form

Redeeming activates a gift certificate balance for the current user. Once this code is active, it will be automatically deducted from any purchase made by this user while logged in with an active session. Another user can enter the same code at the same time, but for security's sake only the first to check out using this code will be able to use it.

NOTE: The only method to redeem a gift certificate code is through this form. Adding a gift certificate code to a standard CartThrob form will not work. 
{exp:cartthrob_gift_certificates:redeem_gift_certificate_form}

    <input type="text" value="" name="gift_certificate_code" /> 
    input type="submit" name="Submit" /> 

{/exp:cartthrob_gift_certificates:redeem_gift_certificate_form}

Displaying information about active and purchased gift certificates

balance

Outputs the amount of active gift certificate balance for the current session

{exp:cartthrob_gift_certificates:balance}

applied

Outputs the amount of active gift certificates that have been applied to the current total.

{exp:cartthrob_gift_certificates:applied}

cart_total_minus_gift_certificates

Outputs the cart total with gift certificate deducted

{exp:cartthrob_gift_certificates:cart_total_minus_gift_certificates}

total_gift_certificates

This tag applies only to logged in member. Gets current total gift certificate balance for this member. This includes gift certificate amounts have been purchased by this member and gifted to other members but not spent.

{exp:cartthrob_gift_certificates:total_gift_certificates}

active_gift_certificates

This is tag is a variable pair. It applies to the current session only. It outputs information about gift certificates that have been applied to the current customer's session.

Example
{exp:cartthrob_gift_certificates:active_gift_certificates}
    balance {credits}                             
    description {description}                         
    status {status}                              
    expires {expires}                             
    order_id {order_id}                            
    gift_certificate_code {gift_certificate_code}               
    gift_certificate_note {gift_certificate_note}               
    gift_certificate_email_address {gift_certificate_email_address}      
    member_id {member_id}                           
    id {id}                                  
{/exp:cartthrob_gift_certificates:active_gift_certificates}

gift_certificates_data

Outputs information about gift certificates purchased by this member, or connected to a specific order_id

This is tag is a variable pair. If no order_id is supplied, it automatically applies to the logged in member.

// Member Specific 
{exp:cartthrob_gift_certificates:gift_certificates_data}
    balance {credits}                             
    description {description}                         
    status {status}                              
    expires {expires}                             
    order_id {order_id}                            
    gift_certificate_code {gift_certificate_code}               
    gift_certificate_note {gift_certificate_note}               
    gift_certificate_email_address {gift_certificate_email_address}      
    member_id {member_id}                           
    id {id}                        
{/exp:cartthrob_gift_certificates:gift_certificates_data}

// order id specific 
{exp:cartthrob_gift_certificates:gift_certificates_data order_id="123"}
    balance {credits}                             
    description {description}                         
    status {status}                              
    expires {expires}                             
    order_id {order_id}                            
    gift_certificate_code {gift_certificate_code}               
    gift_certificate_note {gift_certificate_note}               
    gift_certificate_email_address {gift_certificate_email_address}      
    member_id {member_id}                           
    id {id}                        
{/exp:cartthrob_gift_certificates:gift_certificates_data}

gift_certificate_redemptions

Outputs information about gift certificate redemptions by this member, or connected to a specific order_id.

This is tag is a variable pair. If no order_id is supplied, it automatically applies to the logged in member.

// Member Specific 
{exp:cartthrob_gift_certificates:gift_certificate_redemptions}
    certificate_id {certificate_id}
    credits_used {credits_used}
    balance {balance}
    status {status}                              
    order_id {order_id}                            
    member_id {member_id}                           
    id {id}               
{/exp:cartthrob_gift_certificates:gift_certificate_redemptions}

// order id specific 
{exp:cartthrob_gift_certificates:gift_certificate_redemptions order_id="123"}
    certificate_id {certificate_id}
    credits_used {credits_used}
    balance {balance}
    status {status}                              
    order_id {order_id}                            
    member_id {member_id}                           
    id {id}                        
{/exp:cartthrob_gift_certificates:gift_certificate_redemptions}

Email Variables

Using CartThrob Notifications, you can assign a template to be used as an email notification upon successful purchase of a gift certificate. You can add the following variables to your email notification template that will be sent to the gift receiver.

WARNING: These variables will only render when sent from the notification system. While viewing a notification template in the standard EE template output view, you will not see the final content of these variables.

gift_certificate_note

This outputs the gift note that was (optionally) set when the gift certificate was added to the cart.

{gift_certificate_note}

gift_certificate_code

This outputs the gift certificate redemption code, needed to redeem this gift certificate balance in the redeem_gift_certificate_form noted above.

{gift_certificate_code}

gift_certificate_amount

This outputs the purchased gift certificate amount.

{gift_certificate_amount}

gift_certificate_email_address

This outputs the email address connected to this gift certificate if it is for an email address other than the purchaser's own email address.

{gift_certificate_email_address}

{if "{gift_certificate_email_address}" !=""}
    here's your gift
{if:else}
    you bought yourself a gift certificate
{/if}

Security

Data storage

When gift codes are purchased, the codes are stored in a separate database from other EE and order data, so that the data can not be accidentally deleted when working with standard EE channel entry data.

Note: Different jurisdictions have rules on deleting gift certificate amounts, or applying maintenance fees over time. Please make sure you understand the rules in your location before modifying stored gift certificate amounts. Additionally, you may want to confirm that you have backups of your database done at regular intervals to ensure the integrity of your data.

Gift Code Locking

Gift codes are locked while a payment transaction is in process. When a customer attempts a purchase, the gift code is locked before the transaction begins. If the transaction fails, the gift code is unlocked, or locked permanently if successful. This ensures that the gift code can not be accessed more than once while a transaction is in process. This is especially important when used with offsite payment gateways that may take minutes, hours, or days to complete a transaction fully. Though more than one user may enter a gift code at the same time, the system will only allow one redemption at a time until the transaction is complete.

Reviewing Redemptions

Gift redemptions are logged and can be reviewed in the addon's "redemptions" page. Each redemption, the redeeming member, related order_id, and current status (if not fully redeemed), as well as amount used and date redeemed are stored and are viewable. Additionally, you can specify a field in the order channel to store the related gift codes used during the purchase.

Modifying and Deleting Gift Codes

You can view and modify each gift certificate in the "view" and "edit" pages. Each gift certificate can be transferred to another member, balances can be adjusted and if needed the certificate can be completely removed. When deleting a gift certificate, it requires a double confirmation of the deletion for data security purposes.

Buy Now