Application Flow

Table of Contents

• How data gets output to the page
• How data gets into the cart
• How inventory is tracked
• How taxes are calculated
• How shipping is calculated
• How discounts are calculated
• How coupons are applied
• When rounding is applied
• How payment is captured
• When email notifications are sent

How data gets output to the page

Use cart_items_info to output captured data to the screen.

How data gets into the cart

Use a CartThrob form tag to add items and information to the cart

• Add itemsadd_to_cart_form to add items to the cart.
• Add customer informationsave_customer_info_form to add items to the cart.
• Update items and customer informationupdate_cart_form to update items in the cart.

How inventory is tracked

Inventory is tracked on a per-entry basis. To set up inventory tracking

1. Decide whether or not you will manage inventory on an item-wide or based on a specific group of item-options. Select the inventory field in CT settings > product settings > product channels. Map your inventory field to the field that will be used to track inventory. If you haven't created an inventory field yet, just add a text field to your channel fields for your product channel.

2. Once you have your field selected you can set inventory per item. Leave inventory field blank to let inventory be unlimited. This works on a per-item basis.

3. Whenever an item is purchased, inventory will be adjusted automatically.

4. You can create a notification to email you when inventory is lower than a specified threshold.

How taxes are calculated

Taxes are calculated based on

1. Tax plugin selected

2. Options set in the tax plugin

3. Customer location

For most tax plugins, you must capture the customer's location before the system will return a valid tax value. Included tax plugins use cascading tax rules... whichever rule matches first will be used first. If you have a GLOBAL option set as the first rule, for instance, it will always be used, since it will always match.

Tax locations are evaluated every time the customer updates their location in a CartThrob form. If you do not want tax values being updated during checkout, capture all customer location information before the customer reaches the checkout form, and do not allow them to update their location at that point, or tax values will be recalculated based on new information and the final billed total may vary from the last total shown to the customer.

Actual tax calculations work like this:

Each item * quantity has tax applied (unless it was added to the cart with the tax_exempt parameter set). All items + tax are added together to calculate the subtotal with tax. Most CT price variables also include a plus_tax modifier to show the price including tax. Please see individual tag documentation for a list of the available plus_tax variables.

How shipping is calculated

Shipping plugins are used to calculate shipping. Calculations depend on the plugin, but generally they're based on customer & item information. Items that are added to the cart with shipping_exempt parameter set will not be included in shipping calculations. If you are using any shipping plugin that sets shipping prices based on the entire cart total, entire cart weight, or entire cart quantity, per-item shipping values will be ignored.

For most shipping plugins, you must capture the customer's location before the system will return a valid shipping value. Included shipping plugins use cascading shipping rules... whichever rule matches first will be used first. If you have a GLOBAL option set as the first rule, for instance, it will always be used, since it will always match.

Shipping locations are evaluated every time the customer updates their location in a CartThrob form. If you do not want shipping values being updated during checkout, capture all customer location information before the customer reaches the checkout form, and do not allow them to update their location at that point, or shipping values will be recalculated based on new information and the final billed total may vary from the last total shown to the customer.

How discounts are calculated

Discount plugins are used to calculate discounts. Create discounts in the discount channel. Choose one of the existing discount types, and create discounts that you'd like to be set cart wide. Discounts are set cart-wide automatically if the conditions are matched. Any discounts that are not valid will be ignored.

You can use the discount_info tag to output the currently applied discounts.

How coupons/vouchers are applied

Discount plugins are used to calculate discounts from coupons/vouchers. Create coupons/voucher codes in the coupons channel. Choose one of the existing discount types, and create coupons that you'd like to be set cart wide. To use a coupon/voucher, the coupon must be added to the cart. You can use the add_coupon_form or any other CartThrob form to add a coupon code. Coupon codes that are invalid will return an error, so it's generally best to allow the customer to add coupons in a form without a lot of other types of data collection.

Only one coupon is valid at a time. If the customer enters multiple coupon codes, previous codes will be replaced.

You can use the coupon_info tag to output the currently applied coupon codes.

When rounding is applied

Rounding is applied to:

• item subtotal
• shipping
• tax
• subtotal
• total
• discounts

Taxes are calculated by getting the tax for each rounded item subtotal and adding them together Subtotals are calculated by adding each rounded item subtotal together - rounded discounts Totals are calculated by adding rounded item subtotals including tax with rounded shipping totals including tax - rounded discounts with taxes reduced.

Generally based on the way calculations are handled discrepancies due to number rounding errors are reduced to a minimum. Because we round early in the process, and add rounded numbers together, the final rounded numbers are consistent with what the customer would expect. All numbers in CT are automatically rounded to at most 2 places. If you have items using 3 or more decimal positions, you will need to modify CartThrob software to suit. Most payment systems do not allow payments of 3 decimal positions or more, which is a primary reason that CartThrob does not allow decimal positions larger than 2 in our rounding.

How payment is captured

Sensitive payment data like credit card numbers and CVV2 numbers are not saved in CartThrob by default. This information is passed directly on to the payment processor, and abandoned by CT at that point. At no time is it saved in Session or to channel entries. Other payment information is captured based on the default requirements of each gateway and the automatically generated gateway fields. You can also capture your own fields during checkout. Any field captured that is a default (see list of standard field names) and is mapped in the order channel settings of CartThrob will be saved. Any custom field captured during checkout that has a corresponding field in the orders channel will also be saved (see adding custom data to orders). Any field captured at any time using the custom_data system with a corresponding field in the orders channel will also be saved.

When email notifications are sent

CartThrob includes a notification system that allows you to send multiple emails based on CartThrob payment triggers as well as status changes. Create email rules linked to triggers and status changes, when one of these events is met, the appropriate email(s) will be sent. Emails can be sent when CartThrob triggers are fired (low inventory, completed, declined, or failed transactions) or when a status is changed in the orders channel.

When is an order "complete?"

EE has entry status settings that you're probably aware of. CartThrob also has its own internal statuses for each order. The two are not directly connected, but you configure CartThrob to automatically set EE statuses based on events triggered by your payment gateway. Payment systems update CartThrob with information about whether a transaction has been approved, failed, declined, or is currently being processed. Whenever CartThrob receives notification of one of these events, it updates its internal status. If you have mapped these triggers in CartThrob order settings to EE statuses, the EE entry status of the order will be updated. The important thing to note is that for the most part, CartThrob is only interested in these payment triggers, and will only update items inventory counts, when a "completed" trigger is set. If you are using offline payments or similar, you should set the trigger to "completed" if you want inventory counts to update automatically.