Taking donations with CartThrob

Overview

If you are only taking donations with CartThrob, your set up may be rather simple. At a minimum all you need to take donations with CartThrob is the checkout_form. Several types of donation methods are outlined below

See Checkout Amounts and Payment Review for the financial difference between item-level and checkout-level permitted pricing.

Use the auto-install template system

Regardless of your chosen method, use the auto-install template system to get started. CartThrob comes with an auto-install template system. In the “installation” settings, you’ll see a “cart_donations” group of templates. Install that. You’ll have a basic donation template set up with associated channels. While this setup won’t be ideal for everyone, it’s a good example of how to set up a cart that takes donations, and is loaded with notes in the templates.

Basic Donations

For new donation templates, prefer adding a real donation item to the cart and allowing the donor to set that item’s price with add_to_cart_form allow_user_price="yes". This produces a donation item row and lets the cart subtotal, saved order, and gateway charge reconcile naturally.

checkout_form allow_user_price="yes" remains available for advanced and legacy workflows. In that mode, the submitted price is the final payable checkout total. It is not a replacement subtotal to which tax and shipping are then added. Existing cart item rows retain their original prices, so item prices, cart subtotal, and final order total can intentionally differ.

Avoid using an empty-cart checkout-level donation as the default workflow. Before the donor submits an amount, the payment UI may be initialized with zero or an amount below the gateway minimum. A real donation cart item avoids that ambiguous initial state.

Create an orders channel

Configure CartThrob to recognize your orders channel
Orders channel data is required to
- output reports in CartThrob’s backend
- capture donor information
- capture payment errors

Create templates

Create an add-to-cart form for the donation item
- Add a price field: <input type="text" value="" name="price" />
- Set the add-to-cart allow_user_price parameter
Create a standard Checkout form template
- Add the gateway_fields variable in the checkout_form tag pair
- Do not add a second checkout-level price field when the donation item already carries the donor’s amount
Display transaction information page (a “thanks” page) (submitted_order_info)
- Display checkout errors if order unsuccessful
- Display transaction id if order successful

Advanced Donations

Create a donations channel

Create a channel for donations if you plan to offer a number of donation options, For example:
- donations with preset pricing levels
- donations that provide different benefits to purchasers
- donations to different groups or charities

Create an orders channel

Configure CartThrob to recognize your orders channel
Orders channel data is required to
- output reports in CartThrob’s backend
- capture donor information
- capture payment errors

Create a purchased items channel

Create a purchased items channel if you plan to allow your donor to display and edit information attached to their donation.
Configure cartthrob to recognize your purchased items channel
Create fields (tutorial…) in the purchased items channel to store configuration data if:
- donor notes can be added
- donations have unique configurations (charity, charity options, mission)
- Personalization is added per donation (memorials, dedications, announcements)

Configure Membership

It’s common to allow donors to register with your site so that they can maintain an account history and store their personal information. If you plan to allow customer membership

Create login, registration, and forgot-password pages
- You can use ExpressionEngine’s built in membership templates. If you find them limited, you can use:
  - Profile:Edit greatly simplifies registration and user maintenance
  - User and Zoo Visitor are also popular methods of simplifying member registration
Configure CartThrob’s member settings as needed

Create an account page where the customer can review account details and past purchases

Use the order items tag combined with EE channel entries tag to output information about past donations.

{exp:channel:entries author="CURRENT_USER" channel="orders"}
    {exp:cartthrob:order_items channel="orders" order_id="{entry_id}"}
        Your purchased {title} for {price}
    {/exp:cartthrob:order_items}
{/exp:channel:entries}

Build your templates

Create templates to do the following:

Add items to the cart (add_to_cart_form)
- Add a price field to the add_to_cart_form form:
```
<input type="text" value="" name="price" />
```
- Set the allow_user_price parameter. This allows the customer to set their own price
- to capture data (for instance a note) collect the data as an item option
```
<input type="text" name="item_options[donor_note]" />
```
View cart (cart_items_info)
- update donations in the cart (update_cart_form)
- delete donations (update_cart_form)
Initiate payment (checkout) (checkout_form)
Display transaction information page (a “thanks” page) (submitted_order_info)
- Display checkout errors if order unsuccessful
- Display transaction id if order successful