CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Upgrading to CartThrob 10

CartThrob 10 is a security-focused major release. It protects financial form settings, final checkout amounts, payment references, and download sources more strictly than CartThrob 9.0.1. Most stores built with CartThrob’s native tags continue to work, but custom forms, custom payment JavaScript, extensions, and older download fields must be reviewed.

If the store sells files, read Downloadable products and CartThrob Download fieldtype before disabling the temporary download compatibility setting. CartThrob 10 validates both the field supplying a file and the file source itself; that validation does not replace the site’s purchase/member authorization.

The Version Review utility is added only to installations upgraded from a pre-10 version. Fresh CartThrob 10 installations start in strict mode and do not show the upgrade-review navigation or temporary compatibility bridges.

CartThrob 10 Version Review overview

Before updating

  1. Back up the database, templates, system/user/config/config.php, and the current CartThrob and Order Manager add-on folders.
  2. Update a staging copy first. Use the same templates, extensions, gateways, product fields, downloads, and external caches as production.
  3. Inventory custom CartThrob forms, checkout JavaScript, checkout/cart/download hooks, remote download URLs, and raw download paths.
  4. If config.php is read-only in production, add both temporary bridge settings before running the updater. Set each to true only when that area still needs migration, otherwise set it to false.
$config['cartthrob_legacy_custom_js_checkout'] = true;
$config['cartthrob_legacy_download_sources'] = true;

These are migration bridges, not general compatibility switches. They do not weaken CartThrob 10’s protected form policy, payment reconciliation, unsafe-network protections, or purchase/member access checks.

Update and review

  1. Back up and replace the CartThrob and Order Manager folders in system/user/addons and themes/user, then run the ExpressionEngine add-on updater.
  2. Purge any CDN, reverse proxy, static-page cache, or third-party template cache. The updater clears ExpressionEngine page and tag caches, but cannot clear external caches.
  3. Open CartThrob → Version Review and allow every check to finish.
  4. Fix definite failures. Inspect and test every manual-review item before selecting Mark reviewed.
  5. Test normal and unusual product types, cart updates, coupons, tax, shipping, downloads, Vault forms, every selectable gateway, and any extension that changes CartThrob data.
  6. Disable or remove each bridge after its area passes testing:
$config['cartthrob_legacy_custom_js_checkout'] = false;
$config['cartthrob_legacy_download_sources'] = false;
  1. Rerun Version Review in strict mode, repeat the storefront tests, and only then deploy the same files and configuration to production.

For the meaning and resolution of every review result, see Version Review and compatibility messages. For form migrations with before-and-after examples, see Updating custom forms for CartThrob 10. For checkout JavaScript written for CartThrob 9 or earlier, see Updating custom checkout JavaScript for CartThrob 10. If the store customizes submitted-order or Processing notification templates, also apply the payment review template update.

What standard forms need

Forms rendered by these native tags create their protected policy automatically:

  • add_to_cart_form
  • multi_add_to_cart_form
  • update_cart_form
  • checkout_form
  • get_live_rates_form
  • add_vault_form
  • update_vault_form

The important exceptions are product scope and custom code. An add_to_cart_form that sets price, shipping, weight, permissions or subscription parameters and adds a product entry must put its trusted entry_id on the tag. A form with no product entry, such as a Subscriptions plan form or an on_the_fly item, needs no entry_id; from 10.0.1 it is accepted when the posted entry ID is absent, blank or 0, and a real entry ID is rejected. A catalog multi_add_to_cart_form granting product-specific permissions must provide authorized_entry_ids. PHP, external template syntax, and extensions still require manual inspection.

New form parameters in 10.0.1

These parameters are added by CartThrob 10.0.1. They do no harm on 10.0.0 — the parameter is simply ignored until 10.0.1 is installed — so you can add them as you prepare templates for the upgrade.

  • Customer-selectable values. Declare the values a customer may choose for a protected parameter, such as a subscription’s terms, with options:<param>="a|b|c" on the form tag, or with a selector tag such as Subscriptions’ subscription_select inside the form. A posted value for a declared parameter must match the list; an undeclared protected parameter stays ignored. See customer-selectable values.
  • Save-card choice. Let a shopper choose to save their card with save_vault_checkbox or save_vault_field_value inside checkout_form, or with options:force_vault="yes|no" on a hand-written control. A fixed force_vault= on the tag still wins. See checkout_form.
  • Item tax class. Assign the Tax By Class class with a signed item_options:tax_class="A" on add_to_cart_form (it wins over the mapped field), or map a Tax Class product field. A posted item_options[tax_class] field is accepted only until the next major version.

Checkout amount changes

Supported built-in Stripe Payments, PayPal Standard, and PayPal Advanced flows finalize a server quote before payment. Render the checkout preview variables near the payment fields, and choose an explicit price_change_handling presentation if the shopper should stop and review a changed total.

{exp:cartthrob:checkout_form
    price_change_handling="review"
    return="store/order_info"}
    <p>Subtotal: {checkout_subtotal}</p>
    <p>Discount: -{checkout_discount}</p>
    <p>Shipping: {checkout_shipping}</p>
    <p>Tax: {checkout_tax}</p>
    <p>Total: {checkout_total}</p>
    {gateway_fields}
    <button type="submit">Continue to payment</button>
{/exp:cartthrob:checkout_form}

When price_change_handling is omitted, the final value is still validated but CartThrob does not add a confirmation presentation. The available explicit modes are confirm, review, inline, and template.

Important compatibility notes

  • pNTX and pNSH values posted by a multi-add form are no longer accepted. Map the product channel’s Tax Exempt and Shipping Exempt fields and save the value on each product.
  • Old independently generated internal authority fields are ignored. There is no configuration switch that restores them.
  • A form left open before the update, or served by an external stale cache, can fail closed and ask the customer to reload.
  • Mark reviewed records who reviewed a finding and an optional note. It does not repair a template or change configuration.

Command-line reviews

The Control Panel is the clearest starting point. For deployment checks or large sites, run the matching CLI reviews from the ExpressionEngine installation:

php system/ee/eecli.php cartthrob:compatibility --complete
php system/ee/eecli.php cartthrob:compatibility --area=forms --complete
php system/ee/eecli.php cartthrob:compatibility:download-values --complete

Treat an incomplete, truncated, stale, or failed scan as unresolved. It cannot establish that strict mode is safe.