A Guide to Currency & Prices for Orders, Invoices, and Quotes

If you’ve ever looked at a var_dump() or var_export() of an order, quote, or invoice object, you might have noticed there are a long list of numbers that are present in that object. Here is a sample taken from an order object:

    'base_currency_code' => 'USD'
    'store_currency_code' => 'USD'
    'order_currency_code' => 'USD'
    'global_currency_code' => 'USD'
    'store_to_base_rate' => '1.0000'
    'store_to_order_rate' => '1.0000'
    'subtotal' => '369.7500'
    'tax_amount' => '0.0000'
    'shipping_amount' => '9.8600'
    'grand_total' => '379.6100'
    'discount_amount' => '0.0000'
    'base_subtotal' => '369.7500'
    'base_discount_amount' => '0.0000'
    'base_tax_amount' => '0.0000'
    'base_shipping_amount' => '9.8550'
    'base_grand_total' => '379.6050'
    'shipping_tax_amount' => '0.0000'
    'base_shipping_tax_amount' => '0.0000'
    'base_to_global_rate' => '1.0000'
    'base_to_order_rate' => '1.0000'
    'subtotal_incl_tax' => '0.0000'
    'base_subtotal_incl_tax' => '0.0000'

There are a lot of fields here and they can be quite confusing.  The goal here is to help you decipher the numbers and explain what they mean.

Note: If the names of those variables don’t look familiar, it’s probably because you won’t see them in the code anywhere. They are accessible via an object’s accessor methods. So to get the ‘base_grand_total’, you’d need to call $object->getBaseGrandTotal(). Sorry for the confusion!

For starters, though, let’s cover a little background on currency.

Currency

It wouldn’t be a good article about money with some discussion about currency. Most people probably won’t have to worry about currency conversion, however, a look at price information would be incomplete without touching on it since it is vital to decoding it. Lines 139 through 155 in app/code/core/Mage/Sales/Model/Quote.php talk about the currency logic Magento uses as well as what to use and not use when dealing with these values.

/**
     * Currency logic
     *
     * global - currency which is set for default in backend
     * base - currency which is set for current website. all attributes that
     *      have 'base_' prefix saved in this currency
     * store - all the time it was currency of website and all attributes
     *      with 'base_' were saved in this currency. From now on it is
     *      deprecated and will be duplication of base currency code.
     * quote/order - currency which was selected by customer or configured by
     *      admin for current store. currency in which customer sees
     *      price thought all checkout.
     *
     * Rates:
     *      store_to_base & store_to_quote/store_to_order - are deprecated
     *      base_to_global & base_to_quote/base_to_order - must be used instead
     */

Magento provides a hierarchal system for managing a currency. Currency can be set globally, at the store or “base” level (for display), and then at the quote and order level based on the customer’s preference. The global currency is used in the backend for setting up prices on products. Even if a store is configured to use a different currency, the prices for the objects will be converted from the base currency to the currency of the store. This is important because decoding the names of the values on the object will require us to know how Magento handles dealing with multiple currencies. (Even if only one is configured and used.)

Keeping in mind the three tiers, if we look closely at the object we can see the three tiers of currency information stored in the values:

            <span style="background: #ff8c90;">'base_to_global_rate' => '1.0000'</span>
            <span style="background: #ff8c90;">'global_currency_code' => 'USD'</span>
            <span style="background: #690;">'base_currency_code' => 'USD'</span>
            <span style="background: #690;">'base_discount_amount' => '0.0000'</span>
            <span style="background: #690;">'base_grand_total' => '379.6050'</span>
            <span style="background: #690;">'base_shipping_amount' => '9.8550'</span>
            <span style="background: #690;">'base_shipping_tax_amount' => '0.0000'</span>
            <span style="background: #690;">'base_subtotal' => '369.7500'</span>
            <span style="background: #690;">'base_subtotal_incl_tax' => '0.0000'</span>
            <span style="background: #690;">'base_tax_amount' => '0.0000'</span>
            <span style="background: #690;">'base_to_order_rate' => '1.0000'</span>
            <span style="background: #8c90ff;">'discount_amount' => '0.0000'</span>
            <span style="background: #8c90ff;">'grand_total' => '379.6100'</span>
            <span style="background: #8c90ff;">'order_currency_code' => 'USD'</span>
            <span style="background: #8c90ff;">'shipping_amount' => '9.8600'</span>
            <span style="background: #8c90ff;">'shipping_tax_amount' => '0.0000'</span>
            <span style="background: #8c90ff;">'subtotal' => '369.7500'</span>
            <span style="background: #8c90ff;">'subtotal_incl_tax' => '0.0000'</span>
            <span style="background: #8c90ff;">'tax_amount' => '0.0000'</span>

In red, we see the global currency as well as the conversion rate from the base (or the store) rate to the global rate. In green, we see nine fields. In blue, there are eight fields. You can tell from these values that we are looking at the dump from an order object because one of the fields listed is order_currency_code. Since we are looking at an order, we know that the fields that are not prefixed with base_ or global_ are in the currency of the order. The green fields are nothing more than the order’s fields recalculated in the base (or store) currency for ease of access.

Totals, Amount, Tax, & Shipping

So we’ve essentially got seven distinct values to work with:

  • discount_amount
  • grand_total
  • shipping_amount
  • shipping_tax_amount
  • subtotal
  • subtotal_incl_tax
  • tax_amount

Discount Amount

This is the dollar value of the discount that was applied to the order.

Shipping Amount

The amount paid for shipping on the entire order.

Shipping Tax Amount

This amount of tax that is paid on the shipping.

Subtotal

The cost of just the products without shipping, taxes, or discounts.

Subtotal Including Tax

This amount of tax that is paid on just the products.

Grand Total

This is the total amount of the order after includes taxes, shipping, and discounts. For an order or quote, this is what would be paid by the customer.

Closing Thoughts

How Magento does it’s calculations is highly configurable. There are many options in the backend that affect how taxes, shipping, and discounts affect the totals and values we’ve seen in this article.

To summarize, Magento stores copies of each of the values in both the currency that the current invoice, order, or quote is in as well as the currency of store.  This allows a programmer to see and use both values.

Share it

Topics

Related Posts

Google and Yahoo Have New Requirements for Email Senders

What ROAS Really Means

Everything You Need to Know About Updating to Google Analytics 4

Contact Us