Currency values in the SOAP API cart / order model

Here's what I've figured out so far:

Order_total, order_value, and amt_to_charge seem to always be the same.  I can't tell when or why they'd ever be different.

Amt_paid_now increases when I apply a gift certificate payment.

Balance_to_charge decreases when I apply a gift certificate payment.

HandlingCharges is the total of all fees.

SubTotal is the order_total / order_value / amt_to_charge minus HandlingCharges.

I got some answers from Ravi Ranjan:

• order_total = the summed price of everything in the order, considering only primary line-items
• order_value = the summed price of everything in the order, considering only "first choice" items when there are alternate / upgrade lines
• amt_to_charge = either order_total or order_value, depending on T_DEFAULTS "Order Amount" being set to "Primary" or "First Choice"
• amt_paid_to_dt = amount paid on the order before it was loaded into the cart
• amt_paid_now = amount paid on the order during the current cart session
• balance_to_charge = amt_to_charge - amt_paid_now
• SubTotal = amt_to_charge - HandlingCharges
• HandlingCharges = the sum of all fees in the order

Gift certificate payments are included in amt_paid_now.

Promo / discount prices and overridden fees are included in the prices and fees.

Payment plans do not affect these numbers.

Followup questions:

What does it mean for a line item to be "primary" or not?

Hi Bryan,

The typical use of alternate/upgrade that I'm familiar with is in fixed seat subscriptions. You might want to renew your subscription seats for next season but request a seating upgrade -- in these cases the box office cannot move seats until all other subscriptions have been renewed or released, and so a kind of "phantom" line item is created to note the upgrade requested. When the box office processes upgrades later, they will resolve the request by either staying with the original primary line item and removing the alternate (in the event that the request could not be satisfied) or by fulfilling the request with the alternate line item and making it the new primary.

I haven't done this in a while so I'm sure the specifics are a little bit different, but that's the general idea as I understand it.