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

Checkout Amounts and Payment Review

CartThrob normally keeps product prices, cart totals, saved order totals, and gateway charges in agreement. Checkout-level overrides and information submitted during checkout can intentionally make some intermediate values different.

This guide explains which value to display, store, or trust at each stage.

Built-in checkout vs custom JavaScript

Finalized server quotes — the thing that keeps {checkout_total}, the gateway charge, and the saved order in agreement — are built in for non-subscription:

  • Authorize.net
  • PayPal Standard
  • PayPal Advanced
  • Stripe Payments

A built-in quote flow is distinct from gateway-specific quote enforcement and payment recovery. Authorize.Net can use the built-in quote presentation, but does not require a quote by default and is not included in the automatic reconciliation capture tracking described below. An explicitly required or supplied quote still follows the normal validation rules.

On those checkouts, print {checkout_total} (and the other checkout_* amounts) inside checkout_form. CartThrob finalizes the quote before it charges.

price_change_handling defaults to none. If tax or shipping recalculates after the page rendered, CartThrob still charges the new total and does not stop to ask the shopper. Set price_change_handling="review" (recommended) if they should see that change. confirm, inline, and template are the other built-in presentations. This is independent of error_handling.

Quotes are not built in for:

  • custom_js="yes" (you turned off CartThrob’s gateway JavaScript)
  • Stripe Payments subscription checkout
  • PayPal Standard subscription checkout

For ordinary Stripe Payments and PayPal checkout with custom JavaScript in strict mode, the integration must implement this sequence before relying on checkout-level amount changes:

  1. validate checkout input
  2. finalize the server quote
  3. confirm with the customer when the total changed
  4. prepare the remote payment from that quote
  5. complete CartThrob checkout against the same quote and remote payment

For those quote-required custom integrations, custom_js="yes" means you own all five steps. This does not make subscription flows quote-capable or require a quote by default for server-side gateways such as Authorize.Net. Legacy compatibility settings can permit older Stripe/PayPal integrations; supplied quotes still validate. How to hook the events, what the bundled tokenizer does with price, and a working skeleton are in Custom checkout JavaScript. Copied 9.0 gateway scripts are compared in Updating custom checkout JavaScript for CartThrob 10. See also Gateway and Subscription Boundaries.

Which control should I use?

Tax, shipping, and price can be set in four different places. They are not interchangeable. Pick one on purpose.

I want… Use this What happens
This product is always tax-free or never ships (a download, a store-pickup SKU, a tax-exempt item). In CartThrob › Products, map that channel’s Tax Exempt and/or Shipping Exempt fields. Put Yes/No (or similar) on the entry. CartThrob reads the current entry whenever it calculates the cart and when checkout is finalized. Change the entry, and the next calculation follows it. You do not put no_tax on every template.
This add-to-cart should skip tax or shipping, even if the product mapping says otherwise (a donation, an on-the-fly item, one special product template). add_to_cart_form no_tax="yes" and/or no_shipping="yes" (aliases: tax_exempt, shipping_exempt). That cart item is stored as exempt. It stays exempt in the cart after the form submits.
This checkout page should charge a different tax, shipping, or total than the cart (free-shipping checkout, tax-free checkout, a fixed donation total). checkout_form price, shipping, and/or tax. tax="0" removes checkout tax. price scales the cart’s item tax to the replaced subtotal, preserving its mix of rates and exemptions. shipping is taxed again from the replaced amount when the tax breakdown is exact, so shipping="0" also removes the tax on shipping. If an extension supplies the tax, see Tax extensions. Applies to that checkout only. It does not rewrite the cart or the product. On that form, print {checkout_total} — not {cart_total}.
Show the cart, or let the shopper change quantity / options / address. cart_info, {cart_total}, update_cart_form. These are the saved cart. They do not take checkout price=, shipping=, or tax= parameters. update_cart_form cannot turn tax or shipping exemption on or off.

Practical rule:

  • If it should still be true on the cart page tomorrow, put it on the product or on add-to-cart.
  • If it is an exception for one checkout template, put it on checkout_form and show the checkout_* amounts.
  • Do not copy checkout parameters onto cart tags. A cart tag cannot honestly inherit instructions from a checkout form that has not rendered.

Calculation Sources and Precedence

For an ordinary product-backed checkout, CartThrob applies calculation sources in this order:

  1. Current product and store configuration. Mapped price, shipping, weight, inventory, modifiers, and tax/shipping exemption fields are read from the current entry data when the cart is calculated and checkout is finalized.
  2. Stored cart choices. Quantity, selected modifier values, coupons, customer information, and shipping selections affect the calculation.
  3. Authorized item overrides. Values intentionally supplied through add_to_cart_form, such as a fixed item price or an explicit item exemption, override the corresponding mapped product value.
  4. Authorized checkout overrides. checkout_form parameters such as price, shipping, and tax override the calculated product/cart amounts for that checkout.
  5. Permitted checkout input. When explicitly enabled, allow_user_shipping replaces shipping and allow_user_price replaces the final payable total.

Checkout overrides do not rewrite the product entry and do not bypass inventory validation. They control the finalized order calculation. Product-backed values are not frozen merely because an item has entered the cart. For example, if an entry is tax exempt when added but is changed to taxable before checkout, the current taxable setting is used when checkout is finalized. Supported built-in payment flows use that finalized amount for both the gateway charge and the CartThrob order. Whether the customer sees an additional review is controlled by the checkout template.

The Four Checkout Stages

1. Current cart

The current cart contains effective item prices, quantities, discounts, shipping, and tax based on the customer and shipping information CartThrob already knows and the current mapped product-entry data.

Use cart tags and variables such as:

  • {cart_subtotal}
  • {cart_discount}
  • {cart_shipping}
  • {cart_shipping_plus_tax}
  • {cart_tax}
  • {cart_subtotal_plus_tax}
  • {cart_total}

These values are accurate for the current cart. They do not include checkout-form input that has not been submitted.

2. Checkout preview

Inside exp:cartthrob:checkout_form, the checkout_* variables begin with the current cart and apply known amount-changing tag parameters:

  • price
  • shipping
  • tax

For example:

{exp:cartthrob:checkout_form
    price="20.00"
    shipping="0"
    tax="0"
}
    <p>Current cart: {cart_total}</p>
    <p>Expected checkout charge: {checkout_total}</p>
    {gateway_fields}
{/exp:cartthrob:checkout_form}

The preview cannot include a checkout-time coupon, a new destination, a new shipping selection, or permitted user amounts until those values reach the server.

3. Finalized checkout quote

The finalized quote is created after CartThrob processes submitted customer and shipping information, shipping choices, coupons, permitted user values, current product settings, checkout overrides, and checkout hooks. It is the server-authoritative calculation used to prepare supported built-in payments.

Extensions can filter the normalized options with cartthrob_checkout_quote_options and observe the stored quote with cartthrob_checkout_quote_finalized. The options hook runs both when a quote is issued and when it is consumed, so it must return deterministic values.

4. Gateway charge and saved order

For a successful supported built-in checkout:

successful gateway amount
    = finalized checkout total
    = submitted-order total
    = saved order total

The gateway charge and saved order total are authoritative for the amount paid. Do not reconstruct the paid amount by adding item rows when checkout-level overrides are allowed.

Product, Item, and Order Prices

A product’s catalog price is a starting value. The effective cart-item price can differ because of sales, modifiers, quantity rules, item-level permitted pricing, on-the-fly items, or hooks.

Saved purchased-item rows preserve item snapshots such as:

  • item price and quantity;
  • item subtotal;
  • item price and subtotal plus normal item tax;
  • item tax and shipping flags;
  • selected item options.

An order-level checkout override does not reprice or allocate its difference across those item rows. Their sum may therefore differ from the saved order subtotal or total.

Use:

  • item variables to describe a purchased product;
  • submitted-order variables immediately after checkout;
  • configured order fields for a saved historical order;
  • the transaction status and remote gateway record to determine payment success.

The presence of an order total alone does not prove that payment succeeded. An order can be created before remote authorization or capture completes.

Checkout Override Rules

These controls take precedence over the corresponding calculated product, store, and cart settings for this checkout.

Checkout control Effect
price="20.00" Replaces the order-level subtotal. Shipping and discount still apply. The cart’s item tax is scaled to the new subtotal, so each item’s rate, tax exemptions and the discount’s tax share carry over; a cart with no taxable items stays untaxed. Set tax to fix the tax instead.
shipping="3.00" Replaces calculated order shipping. Shipping tax is recalculated on the new amount when the tax plugin taxes shipping, so shipping="0" also removes shipping tax.
tax="2.00" Replaces calculated order tax.
allow_user_shipping="yes" with posted shipping Permits the submitted non-negative value to replace shipping. Shipping tax is recalculated on it, as with shipping.
allow_user_price="yes" with posted price Permits the submitted non-negative value to replace the final payable total only.

The legacy checkout-form names no_tax, tax_exempt, no_shipping, and shipping_exempt are not checkout controls. They were historically serialized into checkout requests but never consumed by checkout processing, so they do not change checkout tax or shipping. Use explicit tax and shipping values instead. For product or item exemptions, use the mapped Tax Exempt / Shipping Exempt entry fields or add_to_cart_form no_tax / no_shipping.

Tax extensions

If a tax extension (the cartthrob_calculate_tax hook) supplies your store’s tax, a checkout shipping, allow_user_shipping or price override replaces that amount but keeps the extension’s tax, because CartThrob cannot re-tax a figure it did not calculate. To change shipping for such a store, change it in the cart instead, so the extension calculates tax on it: mark the products Shipping Exempt, offer a zero-cost shipping option, or use a free-shipping discount.

The breakdown is unallocated in that case; CartThrob keeps the extension’s order tax rather than estimating its item and shipping shares.

Fixed price is not an exact final total by itself

This form replaces the subtotal with $20.00:

{exp:cartthrob:checkout_form price="20.00"}

The final charge can still include shipping and tax. To set a $20.00 subtotal with zero checkout tax and shipping:

{exp:cartthrob:checkout_form
    price="20.00"
    tax="0"
    shipping="0"
}

Any applicable discount can still reduce the final total. A fixed price is a subtotal override, not an exact final-total control.

Changing the checkout subtotal does not run the shipping plugin again. A free-shipping threshold is evaluated against the cart subtotal; a checkout price override does not move the cart across that threshold.

Permitted user price is a final-total replacement

This form lets the customer choose the entire amount charged:

{exp:cartthrob:checkout_form allow_user_price="yes"}
    <input type="text" name="price">
    {gateway_fields}
{/exp:cartthrob:checkout_form}

The original subtotal, discount, shipping, and tax remain available as order components, but they may no longer add up to the permitted final total. Receipts, tax reports, exports, accounting integrations, and partial-refund workflows must not assume those components reconcile.

If the customer should choose an item’s price and then have CartThrob calculate tax and shipping normally, use add_to_cart_form allow_user_price="yes" instead.

Reconciliation by Checkout Mode

Checkout mode Saved item prices Saved order components Saved total and gateway charge
Ordinary checkout Effective cart-item prices Calculated cart values Calculated finalized total
Coupon Item prices normally remain unchanged Discount and dependent values are recalculated Discounted finalized total
Fixed price Item snapshots remain unchanged Saved subtotal uses the fixed value Fixed subtotal with finalized discount, shipping, and tax
Fixed shipping or tax Item snapshots remain unchanged Explicit component replaces calculated component Recalculated finalized total
Checkout exemption Item flags remain unchanged Exempt order component becomes zero Recalculated finalized total
Item-level permitted price Selected amount becomes item price Components calculate from that item Reconciling finalized total
Checkout-level permitted price Item snapshots remain unchanged Existing components remain Posted permitted final total

Worked non-reconciling example

A cart can contain:

Subtotal:          $154.17
Discount:            $0.00
Shipping:            $5.00
Tax:                $30.83
Calculated total:  $190.00

If checkout-level allow_user_price permits a final total of $22.50, the saved order total and gateway charge are $22.50. The component fields still describe the original $190.00 calculation. The $22.50 is not stored as a discount or allocated among items.

Coupons

The clearest workflow applies a coupon before payment so the customer reviews an already-discounted cart.

A coupon_code field can also appear inside checkout_form. In that case, the coupon is applied during submission and can change discount, shipping, tax, and total. The rendered pre-submission cart cannot include a coupon the customer has not submitted.

Address-Dependent Shipping and Tax

A location-dependent total may be genuinely unknown when the checkout page first renders. A new address can affect:

  • shipping;
  • shipping tax;
  • order tax;
  • location- or shipping-sensitive discounts;
  • the final total.

Browser autofill can populate billing fields while leaving shipping fields blank or leaving placeholder state, postal-code, or country values selected. Avoid duplicate fields with the same HTML names and avoid meaningful but incorrect placeholder destinations.

For location-sensitive stores, prefer:

  1. collect and save the destination;
  2. select and save the shipping method;
  3. apply coupons;
  4. recalculate the cart;
  5. display a final order review;
  6. proceed to payment.

A flat-rate checkout may reasonably remain on one page when the address cannot change the amount.

The Checkout Designer Owns the Displayed Total

CartThrob guarantees that supported built-in gateways use the same finalized amount CartThrob records. It cannot automatically rewrite arbitrary totals, summaries, buttons, or other price text in a custom checkout template.

The checkout designer is responsible for making the amount shown to the customer as clear and current as the checkout requires. Common approaches include:

  • collecting the destination, shipping option, and coupon before the payment step;
  • using AJAX to apply a coupon or save address/shipping changes and then refreshing the displayed breakdown;
  • updating the displayed total with custom JavaScript; or
  • intercepting ct.checkout.amount-changed to show a same-page panel or modal before continuing.

If none of those presentations is added, CartThrob still charges and records the same finalized amount, but it does not require purchaser confirmation merely because the amount changed after the page rendered.

Changed-Total Confirmation

For built-in Authorize.net, PayPal Advanced, PayPal Standard, and non-subscription Stripe Payments flows, CartThrob finalizes the quote before preparing or completing payment.

If the finalized amount differs from the amount rendered with the checkout form, CartThrob dispatches the price-change events before continuing with the finalized amount.

When price_change_handling is omitted—or explicitly set to none—the default behavior does not interrupt the purchaser. A designer-owned ct.checkout.amount-changed listener can still prevent that continuation and provide a custom interface.

Other presentations are available:

  • confirm shows a browser confirmation with the previous and current totals;
  • review shows an accessible same-page review panel and is the recommended built-in presentation;
  • inline returns to the checkout form with price-change variables;
  • template loads marked content from an internal EE template into a same-page modal. The target uses {exp:cartthrob:checkout_price_change} to control the modal content.

Preserve gateway fields by staying on the checkout page

Hosted payment fields, including Stripe Elements and PayPal Hosted Fields, are secure provider-controlled frames. Their entered values cannot be copied into a redirect URL, session, or ordinary template field.

Any full-page navigation or form re-render can therefore require the customer to enter gateway data again. This can include an inline response that reloads the checkout template, a legacy template target without the new modal marker, or a custom page-changing flow.

To preserve mounted gateway fields, keep the customer on the existing checkout page. Use review, confirm, the marked same-page modal provided by template, a custom panel built with ct.checkout.amount-changed, or AJAX that updates the visible price before the final submission.

These choices are independent of validation error_handling. See the checkout_form price-change reference for parameters, variables, and examples.

Custom interfaces can listen for:

  • ct.checkout.quote-finalized
  • ct.checkout.amount-changed

See the checkout_form reference for the event contract.

The previous browser-visible value is presentation state only. The server-finalized quote remains authoritative for the charge.

Zero-Total Checkout

When the finalized total is zero, CartThrob completes checkout locally without creating a remote provider payment. The order receives an explicit ct-free-* transaction reference so staff and templates can distinguish a local zero-total completion from a gateway transaction. When the order already has a persistent ID, the ordinary form is ct-free-<order_id>.

No provider charge, authorization, order, or PaymentIntent should be expected for that transaction. Treat the ct-free- value as a CartThrob reference, not a remote payment identifier.

Stale Quote and Payment Protection

CartThrob binds finalized quotes to the applicable cart/session state, amount components, currency, gateway, and prepared remote payment.

If that state changes after payment preparation, checkout stops rather than capturing an obsolete amount. This is payment-integrity protection, not an ordinary field-validation error.

Troubleshooting should check for:

  • cart mutations from custom extensions;
  • nondeterministic checkout hooks;
  • currency or gateway changes;
  • duplicated submissions;
  • custom JavaScript preparing a remote payment too early;
  • expired, superseded, or already-consumed quotes.

A superseded Stripe PaymentIntent is canceled when its remote status allows cancellation. A canceled intent for an unfinished checkout is cleanup, not a successful or duplicate charge.

Processing orders and payment reconciliation

A Processing order is not proof of payment. It can mean payment is expected later, a gateway is still confirming payment, or the order needs merchant review.

Situation Meaning Merchant action
Offline Payments set to Processing A check, invoice payment, or other offline payment is still outstanding. Confirm receipt outside CartThrob before completing fulfillment.
Payment confirmed; order needs review Stripe Payments or PayPal confirms collection, but the amount/currency or local checkout completion needs review. Compare the provider payment with the order before fulfilling, refunding, or requesting anything further.
Payment outcome unknown Capture was attempted, but CartThrob cannot confirm its outcome. Look up the original payment at the provider before attempting another payment.

The two reconciliation outcomes use the existing Processing checkout response with an additional payment_review flag. A card authorization without capture is not confirmed collection. A definite decline remains a declined/failed payment response, as appropriate for the gateway.

What happens to a held checkout?

For these Stripe Payments and PayPal reconciliation cases, CartThrob:

  1. Retains the payment reference and available provider evidence, independently of Save Orders and whether Order Manager is installed. Supported server-side captures have an attempt record saved before capture.
  2. Keeps an available saved order and its line items in internal Processing, using the closed order-entry status for the hold. It does not change the order total to match an unexpected charge.
  3. Withholds new Purchased Item entries, subscription completion, permission grants, and the normal successful-checkout inventory/discount processing. Ordinary offline Processing keeps its existing behavior.
  4. Sends configured Processing notifications with the review reason, clears the cart, and uses processing_redirect. The customer is told to contact the store with the reference and not pay again.
  5. Preserves the terminal response for duplicate submissions using the same form key. An unresolved capture attempt must not initiate another capture.

The special hold does not call cartthrob_on_processing or cartthrob_order_created; those hooks may trigger fulfillment integrations. It does not send a completed-transaction receipt. Configure a Processing notification if the merchant should receive email; an incident is still available in the control panel without an email notification.

If local completion fails after authorization or fulfillment already happened, CartThrob retains the incident without downgrading the completed order or undoing those effects. Check the order as well as the provider payment.

Find and reconcile the payment

Open CartThrob → Payment reconciliation. This page is available in both legacy and strict modes, including fresh installs, and does not require a compatibility scan. It shows up to 50 unresolved incidents with:

  • last occurrence, review reason, and reported provider state;
  • gateway and payment references, including a related order/capture reference where available;
  • the provider amount and expected checkout amount, when known; and
  • the saved order ID, linked to Order Manager when installed.

Blank amounts mean the value was not established; they do not mean zero. A reported provider amount on an older incident does not by itself establish collection. Check the reason and provider state.

Order Manager also labels affected orders and shows a notice on the order. While an incident is unresolved, its capture, void, and refund controls are unavailable, and payment-action requests are blocked. Use the provider’s records to establish the outcome and handle any necessary correction.

Choose a resolution based on what happened to the payment. Use Complete paid order for an eligible payment you have verified and accepted; use Mark reconciled for refunded, unpaid, or manually handled outcomes. The latter records the finding without marking the order paid, creating purchase entries, or sending a Completed notification. Changing an EE entry status alone also does not complete checkout. The available outcomes are below.

Choose a resolution or complete a paid order

Expand Resolution options on the incident and choose an outcome:

Outcome Submit action Result
Payment verified and accepted Complete paid order — no charge Completes the supported local checkout work. Accepted amount must equal the original order total and currency.
Payment accepted with an adjustment Complete paid order — no charge Completes locally after you record and accept a difference, such as a discount, separately collected balance, or partial refund.
Refunded / canceled — no fulfillment Mark reconciled Records a refund or cancellation already handled; creates no purchase entries or paid benefits.
No payment collected — no fulfillment Mark reconciled Records the finding without fulfillment or another payment attempt.
Already handled manually Mark reconciled Records work already performed without repeating it.
Still uncertain Leave the incident open Investigate the original payment before resolving it.

Paid outcomes require a verification checkbox, accepted net amount and currency, a verification/adjustment reference, and a resolution note. The currency must match the original order. Refunds and additional payments must be handled separately before recording them here. No resolution button charges or refunds money.

An accepted adjustment preserves the original order total, product prices, tax, shipping, and provider observations. It records the amount the merchant accepts for fulfillment; it does not redistribute a discount or recalculate an invoice. Record any required accounting correction separately.

For eligible saved ordinary orders, Complete paid order creates missing Purchased Item entries when configured, processes inventory and original coupon/discount use, grants applicable ordinary item permissions, sets the internal paid and configured EE order status, invokes authorized/order-created hooks, and dispatches configured Completed notifications. It uses the saved checkout and customer ownership rather than the administrator’s form data. Custom hooks run in a CP request and should obtain customer identity from the order rather than assume the current CP member is the customer.

The original hold still sends Processing notifications and withholds new Purchased Item entries. Mark reconciled alone sends no checkout notification and creates no entries. Configured status-change notification rules remain independent.

Automatic completion needs a recovery snapshot saved when the new hold was created. Earlier incidents without one, changed/missing required order data, account-creation or subscription work, and orders already partly completed need manual handling. The page shows when the saved context is unavailable or requires manual completion; it does not reconstruct a missing order.

Duplicate clicks cannot claim the same order again. If a step fails or the request stops, the page shows the last completion step and retains the incident. Inspect the entries, stock, permissions, and notification logs; finish any missing work manually before selecting Already handled manually. This avoids automatically repeating uncertain fulfillment or email effects. If local completion finished and only incident resolution failed, resubmitting the exact same paid resolution closes the incident without repeating completion.

Order Manager displays the recorded outcome, accepted amount/currency when applicable, reference, note, member ID, and time. Adjusted, refunded, unpaid, and manually handled resolutions keep its capture/void/refund controls disabled: use the provider for later payment actions because the original order total alone may no longer establish the refundable amount. An accepted payment with no adjustment returns to ordinary Order Manager payment-action rules.

Customer templates and custom JavaScript

On the checkout result page, check {if payment_review} before generic Processing or success messages. Use payment_review_kind to distinguish confirmed from unknown, and display the supplied message/reference. See submitted_order_info.

For a custom AJAX completion request, payment_review=true is a terminal result requiring attention. It still has success=false; do not treat that as permission to retry payment. Present the message or navigate to the returned Processing URL. See Custom checkout JavaScript and Processing notifications.

Which gateways are covered?

CartThrob 10 provides the following automatic reconciliation coverage:

Gateway/path Automatic reconciliation coverage
Stripe Payments, ordinary quoted checkout Supported capture-attempt tracking and verified collection evidence.
Stripe Payments, eligible legacy ordinary checkout Verified already-collected payments can produce a review incident once the server establishes the payment evidence.
PayPal Standard, finalized-quote checkout Records the capture attempt before requesting capture; distinguishes confirmed collection from an uncertain response.
PayPal Standard, legacy ordinary checkout Checks the posted payment reference with PayPal; verified completed payments can produce a review incident. A failed lookup before evidence is established is not automatically recovered.
PayPal Advanced, ordinary checkout Tracks the server-side capture attempt in both its quoted and legacy charge paths and checks the completed capture evidence.
Authorize.Net, including Accept.js and stored-profile charges Not currently integrated with the new capture-attempt/collection evidence workflow.
Other gateways, recurring flows, and explicit Order Manager captures Do not assume coverage from these PRs.

A supported incident is eligible for Complete paid order only when its original ordinary checkout recovery context is available and passes the checks above. Not every incident has enough data for automatic completion.

PayPal needs the same merchant verification as Stripe: check the actual capture and its amount/currency, not merely the buyer’s approval or PayPal order ID. Keep both order and capture references when available. PayPal Standard’s quoted flow uses the capture ID as the transaction reference; PayPal Advanced keeps the PayPal order ID as transaction_id and stores the capture ID separately. Refunds for these two gateways are performed in PayPal before recording the resolution in CartThrob.

Authorize.Net’s Accept.js token represents payment details; CartThrob sends the amount in the subsequent server-side authorize/purchase request. This avoids the same browser-collected stale-amount mismatch. It does not eliminate a lost response after a purchase or a local failure after the provider succeeds. The current Authorize.Net code does not persist the new attempt/collection evidence, so those failures do not automatically receive this reconciliation workflow. Check Authorize.Net before retrying an uncertain payment. Authorize Only also differs from collected payment and must not be treated as paid recovery.

Quote validation protects what is requested before payment. Durable payment evidence handles what happened after a request was sent; one does not replace the other. The new reconciliation PRs do not modify Authorize.Net’s charge implementation.

Limits

This handling covers the supported Stripe Payments and PayPal checkout paths, not every gateway or recurring-payment integration. It applies in both compatibility modes and does not weaken quote, amount, currency, or ownership checks.

A browser-collected payment followed by no request reaching CartThrob, or a checkout rejected before trusted payment evidence can be established, may still need manual investigation at the provider. This feature does not add webhook or scheduled payment recovery. Storage failures after collection can also limit the local evidence available.

An actual amount mismatch retains the expected and collected amounts. A matching legacy payment followed by a later completion failure may have only the collected amount/reference in its incident record. With Save Orders off, a fresh form key can produce another notification for an existing incident; the same form-key replay remains protected.

Gateway and Subscription Boundaries

The built-in finalized-quote flow is the contract in Built-in checkout vs custom JavaScript. It covers non-subscription Authorize.net, Stripe Payments, PayPal Standard, and PayPal Advanced.

Do not assume identical behavior for:

  • custom_js="yes", which disables CartThrob’s gateway JavaScript so your code owns validation, quote, confirmation, prepare, and submit (Custom checkout JavaScript);
  • Stripe Payments subscription checkout;
  • PayPal Standard subscription checkout.

Those flows must not use amount-changing checkout controls unless their integration implements the same five-step sequence.

Security and Business Rules

allow_user_price and allow_user_shipping deliberately trust the customer to choose a valid non-negative amount. A hidden browser field is still customer-controlled.

Use these controls only for intentional workflows such as donations, pay-what-you-want items, or administrator-assisted checkout. Enforce minimums, maximums, and other business rules on the server.

For new donations, prefer a real on-the-fly or product-backed donation item with item-level permitted pricing. Avoid empty-cart checkout-level donation forms: they can initialize a gateway payment UI from a zero or below-minimum cart before the browser-entered amount has been submitted.