CartThrob Credits Version 1.21

Overview

CartThrob Credits lets members purchase credits and spend those credits against cart totals.

Core behavior in current package:

• Credits are stored per member in cartthrob_credits_credits.
• Credit redemptions are tracked in cartthrob_credits_redemptions.
• Credits can be auto-applied during checkout through extension processing.
• Credits can also be added through dedicated credit forms/actions.

Requirements

• ExpressionEngine 2.5+
• CartThrob 2.2+
• PHP 5.3+

Installation

1. Upload cartthrob_credits to /system/expressionengine/third_party/.
2. Install CartThrob Credits from the Add-ons page.
3. Configure settings in the add-on control panel.

Upgrading

1. Upload updated cartthrob_credits files over the existing add-on.
2. Run add-on updates from the EE Add-ons page.
3. Recheck Credits settings.

Start Here (10-Minute Setup)

1. Open Add-ons > CartThrob Credits > System Settings.
2. Set Default Conversion Rate.
3. Set Order Channel Credits Field if you want credits used written onto order entries.
4. Set Auto Apply Credits based on your checkout model.
5. Add test credits to your account in Add/Edit Credits.
6. Place {exp:cartthrob_credits:cart_total_minus_credits} and {exp:cartthrob_credits:credits} in your checkout templates.

Common Tasks With Examples

1. Show Member Credit Balance

{exp:cartthrob_credits:credits}

2. Show Cart Total After Credits

{exp:cartthrob_credits:cart_total_minus_credits}

3. Sell a Product That Grants Credits

{exp:cartthrob_credits:add_to_cart_form entry_id="{entry_id}" credits="10" return="cart/index"}
    <input type="submit" value="Buy and add 10 credits" />
{/exp:cartthrob_credits:add_to_cart_form}

4. Add Credits From a Form Action

{exp:cartthrob_credits:add_credit_form price="20" return="account/credits"}
    <button type="submit">Buy Credits</button>
{/exp:cartthrob_credits:add_credit_form}

Quick Links For Existing Users

• Need conversion behavior: see System Settings.
• Need member balances: see Credits List.
• Need redemption reporting: see Redemptions.
• Need tag reference: see Template Tags.

Control Panel Reference

Credits List (.../view)

Table columns:

1. Member info (screen_name, ID, member CP link)
2. Credit total
3. Actions (Edit, Delete)

Redemptions (.../redemptions)

Table columns:

1. Member info
2. Credits redeemed
3. Amount
4. Order ID (or processing/offsite status)
5. Date
6. Redemption status

Add Credits (.../add)

Form fields:

1. member_id
2. credits

Submit creates a credit row or updates member credits through save logic.

Edit Credits (.../edit)

Form fields:

1. member_id
2. credits
3. delete_credit checkbox

Delete Credits (.../delete)

Form fields:

1. hidden id
2. delete checkbox confirmation

System Settings (.../system_settings)

Form fields:

1. default_conversion_rate
2. order_channel_credits_field
3. auto_apply_credits (true/false)

Template Tags

cart_total_minus_credits

Outputs cart total after applying available member credits.

Parameters:

• member_id (optional; defaults to logged-in member)
• order_by (optional)
• limit (optional)
• offset (optional)

Example:

{exp:cartthrob_credits:cart_total_minus_credits}

credits

Outputs total credits for the resolved member.

Parameters:

• member_id (optional; defaults to logged-in member)

Example:

{exp:cartthrob_credits:credits}

credits_data

Tag pair for credit row data.

Parameters:

• member_id (optional; defaults to logged-in member)
• order_by (optional)
• limit (optional)
• offset (optional)

Variables (from credits row):

• id
• member_id
• order_id
• timestamp
• expires
• status
• description
• credits

Conditional:

• {if no_results}...{/if}

redemptions

Tag pair for redemption row data.

Parameters:

• order_id (optional; when set, redemption query is by order)
• member_id (optional; defaults to logged-in member when order_id not set)
• order_by (optional)
• limit (optional)
• offset (optional)

Variables (from redemption row):

• id
• member_id
• order_id
• timestamp
• credits_used
• amount
• status
• cart_id

Conditional:

• {if no_results}...{/if}

add_to_cart_form

Creates a CartThrob add-to-cart form with credits support.

Parameters:

• standard cartthrob:add_to_cart_form parameters
• credits (optional override for credit amount granted)
• logged_out_redirect (optional)

Behavior:

• if credits is set, that value is stored for the cart item
• if credits is not set, a marker is stored so conversion-rate logic can be used

add_credit_form

Creates a form that posts to Credits add_credit_action.

Parameters:

• price (optional encoded amount)
• order_id (optional encoded order source)
• allow_user_price (optional)
• return / secure_return (optional)
• logged_out_redirect (optional)

Checkout and Processing Behavior

Extension hooks used by the add-on:

• cartthrob_pre_process
• cartthrob_on_authorize
• cartthrob_on_fail
• cartthrob_on_decline
• cartthrob_add_to_cart_end

High-level flow:

1. Pre-process can apply available credits and reduce checkout total.
2. A redemption record is created while processing.
3. On authorization, redemption is finalized and order linkage is written.
4. If a credit product is purchased, credits are added to the member account.
5. On fail/decline, redemption state is rolled back appropriately.