Is there any documentation on the difference between these, and how they may or may not be related?
I'm loading renewal orders and the CartAmount is null, which is unexpected.
BalanceToCharge: The actual amount that needs to be paid at Checkout which would not include money previously paid on the order nor any on-account money or gift certificates applied to the order in the session.
CartAmount: The full value of the order including previous payments applied and any on-account or gift certificates applied during the session.
If the key "Order Amount" exists in T_DEFAULTS for the current session’s web organization with a value of "First Choice" the amount of the products in the cart is the value of the first choices on all of the line items; If this key's value is "Primary" or if the key does not exist the amount of the products in the cart is the value of the primary lineitems.
CartFirstChoiceAmount: The current full value of the order, calculated using First Choice Lineitems
CartPrimaryAmount: The current full value of the order, calculated using Primary Lineitems.
------
CartPrimaryAmount and CartFirstChoiceAmount both have to do with Subscriptions, and the ability for customers to request upgrades on the seats assigned to them in package orders.
These two values are used in a column called "Priority" in a Subscription upgrade table. More information can be found here.
There is a T_DEFAULTS setting for "Order Amount", that determines whether the amount to pay on a subscription web order is based on the value of the primary line item (default_value = Primary) or on the value of the first choice upgrade (default_value = First Choice) requests. If no row is present, the value is assumed to be Primary.
However, while “upgrade” is for subscription seating (and CartPrimaryAmount and CartFirstChoiceAmount determine which price to use), if the cart doesn't have a subscription, CartPrimaryAmount will contain the cart's value total, because there is no key for that.