Aller directement à la fin des métadonnées
Aller au début des métadonnées


To be able to record a tax percentage against purchasable entities such as memberships, event fees and other financial types and produce the relevant accounting lines within CiviCRM.

  • Tax is normally posted to a liability account
  • Multiple tax’s can be applied to a single item such as state tax and city tax
  • Customers need to be made aware of the tax element and associated costs on their purchase
  • Additional Country/jurisdiction specific tax rules will be implemented via hooks or a full extension per country/jurisdiction
  • There are benefits to having all extensions store their data in the same core fields even if each country's tax rules are in separate extensions
  • There are benefits to having all extensions implement rules / hooks in a similar way

 Implementation Guidelines

 CiviAccounts has a variety of features that can be leveraged to allow the recording of tax related information for the relevant entities

User Journeys

The following are proposals for the steps a user would be expected to complete in order to indicate an item is taxable. Three alternate setups have been proposed.

[Sales Tax User Journey - Proposal 1] - Parvez Saleh

[Sales Tax User Journey - Proposal 2] - Andrew Perry

[Sales Tax User Journey - Proposal 3] - Lola Slade

Batching contributions for Export

I think the screens for creating the finance batches need some TLC. Some suggestions would be

  • Batch Totals should be based on credit/debit amounts not just a summation of all contributions. In my case ($120 contribution including $5 fees, $20 Tax) the batch assigned total is showing $145. This seems wrong as its greater than the total value. If debits/credits where shown with account type summary it may make more sense. Whichever route is chosen the total should never exceed the total contribution value.

JM: Normally the fees are supposed to be deducted from the total amount of the transaction. Taxes as I understand it should be included in the Total. So the Total Amount should be $140 in the example (where the 'contribution' is actually a payment for a good or service that is taxable).

 Output for Accounting Exports

An example of an export file is as below

Transaction Date    Debit Account    Debit Account Name     Debit Account Type    Debit Account Amount (Unsplit)    Transaction ID (Unsplit)    Payment Instrument    Check Number    Source    Currency    Transaction Status    Amount    Credit Account    Credit Account Name     Credit Account Type    Item Description

01/05/2013 23:27    1150     Payment Processor Account    BANK     120        Credit Card         USD     Completed     100     4400     Member Dues                         INC        Contribution

01/05/2013 16:32    1150     Payment Processor Account    BANK     120        Credit Card         USD     Completed     20        2202     VAT 50% Rate                       VAT50    VAT

01/05/2013 23:27    5200     Banking Fees                          EXP        5           Credit Card         USD     Completed     5         1150     Payment Processor Account    BANK     Fee


The above is based on

  • Contribution: $100
  • Tax $20
  • Total payment $120 ($100 + Tax 20%)
  • Credit Card Fees $5

JM: I have changed this to ensure there is a revenue account and balanced transactions. This results in $100 flowing to a revenue account, $20 to VAT account, with both matched against a payment processor account (balancing $120 against $120). See CiviAccounts Data Flow#OnlineorofflinecontributionwithFEE for prototype for how fees should be stored (nothing changes due to Sales Taxes being applied in transaction). See CiviAccounts Data Flow#ContributionwithSalesTax for description of additional records and changes to handle Sales Tax from default contribution case. To clarify with some sample records corresponding to the above:

civicrm_contribution: total_amount=120.00

civicrm_financial_trxn: id=x, amount=120, to_financial_account_id derived as per CiviAccounts Data Flow#Onlinecompletedcontribution (ie retrieve payment processor's financial account via linked civicrm_entity_financial_account), from_financial_account_id: NULL

civicrm_line_item: id=n, line_total=100.00 (NB: NOT 120, and there is NO additional line item for the sales tax, so for contributions with Sales Tax it is NOT true that sum of line_total for line_items = civicrm_contribution.total_amount)

civicrm_financial_item: two are created, both linked to record as follow:

id=y (as spec'd for default contribution)

  • entity_table: civicrm_line_item
  • entity_id: n
  • amount: 100.00
  • financial_account_id: corresponding to member dues 4400 account

id=y+1 (new for sales tax)

  • entity_table: civicrm_line_item
  • entity_id: n
  • amount: 20.00
  • financial_account_id: corresponding to VAT50 2202 account

Also, add an additional civicrm_entity_financial_trxn record to link the civicrm_financial_trxn record with id=x, total_amount=120 to the new sales tax financial_item: entity_table = 'civicrm_financial_item', entity_id = y+1, amount = 20.00.

Interaction with Webforms payments

Webforms 4.4+ now allows to take payments for events / membership.

Given that all payments for webforms are processed through contribution pages we must check that the Tax rules apply to any payments made through webforms. (The contribution page should dictate the financial type of the transaction and therefor the same rules as above should apply - but this should be confirmed and if not working properly fixed).

From looking at the way the forms are set up I think it will only be possible to apply the same tax rate to all of the amounts on any single webform as there is no way to specify a financial type for each of the "amount" field elements. This will be fine for now but Coleman may in future want to visit this.

Users can write in the label of the appropriate Inclusive/exclusive from tax on the webform itself so no need to modify webforms to split this out.

Changes required to the core

Financial Account Allow Tax up to 99.9999%

The table definition of civicrm_financial_account now allows 8 decimal places (see 

Add 'Sales Tax Account is' to the possible list of relationships

A separate Account Relationship is set up for each place in code where something different occurs depends on the linkage to the financial type. CiviCRM can support other types of liability accounts, such as accounts payable accounts for grants (coded via extensions) and refunds. Different Account Relationships will allow these different types of accounts payable accounts to be specified.

In order to link the tax account to the financial type an appropriate account payable relationship type is required

     (@option_group_id_arel, 'Sales Tax Account is', 10, 'Sales Tax Account is', NULL, 0, 0, 10, 'Sales Tax Account is', 0, 1, 1, 2, NULL),

Add option to CRM_Financial_Page_AJAX to ensure liability accounts are returned when payable option is chosen

      $financialAccountType = array(
        '5' => 5, //expense
        '3' => 1, //AR relation
        '1' => 3, //revenue
        '6' => 1, // asset
        '7' => 4, //cost of sales
        '8' => 1, //premium inventory
        '9' => 3, //discount account is
        '10' => 2, //sales tax liability 

 Allow multiple sales tax accounts to be linked to a single financial type

This will allow multiple tax rates to be applied to a single entity for example a state tax and a city tax.*

Note, to support putting two sales taxes in a specific order on forms, we will add a weight column.

Change xml/schema/Financial/EntityFinancialAccount.xml to include a weight field, and on upgrade add a weight field and fill with current id of each record. For field definition, something like:

ALTER TABLE civicrm_entity_financial_account ADD weight int(10) unsigned NOT NULL COMMENT 'determines order with higher weights lower on page and to the right';

Change the code in:

a) civicrm/admin/financial/financialType/accounts?action=update&id=9&aid=3&reset=1 to allow more than one relationship to be specified for 'Sales Tax Account is', and to expose the new weight field for editing, and

b) civicrm/admin/financial/financialType/accounts to support a weight column with standard links arrows up or down to rearrange entries in table.

JN - *To confirm that we would only require up to 2 sales accounts to a linked FT.

Require Sales Tax accounts to be tax accounts

When a Sales Tax Account is relationship is specified on civicrm/admin/financial/financialType/accounts, require the Financial Account to have Is Tax? enabled.

Include Tax on display forms

Tax UI changes - Other

Proposed Tax UI changes - other 2

Keep the total tax amount against the contribution

Tax UI changes - Other

Proposed Tax UI changes - other 2

Although there would be some data duplication, for reporting purposes it was agreed this would be best.

Generate additional trxn lines if a tax_amount is set

Add new method to CRM_Core_BAO_FinancialTrxn::recordTax($params). Note this method differs from the other methods, e.g. recordFees, as it will need to iterate through more than one liability tax account.

Call from CRM_Contribute_BAO_Contribution::recordFinancialAccounts

Conditional on CRM_Utils_Array::value('tax_amount', $params)

If all changes are made we should end up with the following additional data

  • An extra row in civicrm_financial_trxn per liability account with the correct percentage break down
  • An extra row in civicrm_financial_item per new civicrm_financial_trxn record linking the transactions together
    • JM: this seems wrong to me - if there is a state tax and city tax on each line item then there should two * number of line items more in the financial_item table, and no additional civicrm_financial_trxn records.
  • Two record per liability in civicrm_entity_financial_trxn per liability account linking the contribution to the generated line items
    • Correct errors above, and follow existing pattern for linking a financial_trxn to a financial_item (so there will be 2 * number of line items more entity_financial_trxn if each line item has two taxes).

Show Tax on View Contribution

Currently the view contribution page shows total/net/fee amounts. It should also show the tax amount(s) charged for the contribution, with the total for each tax on a separate line.

Tax UI changes - Other

Proposed Tax UI changes - other 2

Show Tax on Contribution Receipts

The contribution receipts should also show the tax amount(s) charged for the contribution, with the total for each tax on a separate line.

Modify standard receipts

Allow Hook to amend the liability accounts used to calculate tax and the amount of tax

In some situations a change to the sales tax accounts/rate is required. For instance in some countries which tax account represents the applicable provincial or municipal tax varies according to the purchase contact's region, which is derived from their address. Similarly, there may be a need to modify the default calculation of a sales tax based from being a percentage associated with the type of sales tax.

  • Aucun
  1. May 08, 2013

    Chris Ward dit :

    Looks great, you can add Australia as another country that needs this kind of functionality, also the ability to add ton only certain contributions / transactions.

  2. May 08, 2013

    Mark Sherman dit :

    From the U.S. centric position that I'm in, this looks a bit skimpy.  We've had groups that sell a product as an annual fundraiser  (one sells New Mexico Chiles, absolutely fabulous, by the way) and we've used the online event sign up with price sets to handle it.  They also sell Tshirts and books. Each product type can have different tax rates. There can also be different sales tax rates for the same product within different regions of a single state. So if the product is being shipped to a section of the state that has a different tax rate then the region of the state that the organization is in, the sales tax rate to be used in the calculation is different. You can use zip code to approximate the region and determine the rate applicable, but it's not 100% accurate. Up to now, organizations do not have to collect tax on products shipped out of state. This all means that the same product can have no sales tax or several different applicable sales tax depending on where it's being shipped to.    Some states tax on shipping costs. Some do not.

    I guess the point of this post is essentially to say congrats on this addition to CiviCRM, but U.S. folks should adopt it cautiously and probably will need to look at a shopping cart for sales tax calculations.

    1. May 08, 2013

      JoeMurray dit :

      We've added a hook to allow the rates to be changed based on the purchaser's address. If there is open source information regarding the applicable taxes and their rates, eg if it is developed for Drupal Commerce, then it could be used in a new extension. The expectation has always been that there would need to be different extensions for different jurisdictions.

  3. May 19, 2013

    Yves Lavoie dit :

    Multiple taxes can be simple, i.e. all based on sale price of the item or compounded, i.e. each applied tax is calculated, added to the sale price and the new total serves as basis for subsequent taxes (Quebec PST was calculated over Canada GST + item price up to last january, for example)

    Will CiviCRM support both?

    1. May 19, 2013

      JoeMurray dit :

      My comment above in the page was inaccurate given other aspects of the way financial items are related to the line items. I understand that the implementation will allow multiple sales taxes to be applied to each line item.

  4. Jun 01, 2013

    Andrew Perry dit :

    Great examples of the user journey for this approach.  I think it can be simplified and suggest a different user journey that can be documented either as an update to this page or as another page.

    For Step 1, I disagree that each tax rate should be a financial account as this is confusing the concepts of financial accounts with "Tax Rules".

    We will make Financial Accounts unnecessarily cluttered and confusing for people if we mix tax issues in with them.

    There should be a new entity called a "Tax Rule".  Some of this may be editable via the UI, however the rule itself may be sufficiently complex that it needs to be in XML/code.

    How I originally envisaged tax rules to work as part of CiviAccounts is outlined in more detail on the forum here:,28955.0.html

    Below is my alternative to some of the steps above which will simplify the UI.  I haven't commented on each section above, but changes to other sections would likely be required based on the changes below.

    Alternative Step 1: Tax Rules

    The Tax Rule page would show a list of Tax Rules.

    The "Add Tax Rule" page would enable you to provide:

    Label: <what appears on the screen/receipt>

    Alias: <what appears in drop-down boxes where you can select this rule>

    Applies to: <blob of XML/code or drop down list of XML/"tax rule extensions" on the filesystem>

    Calculation Method: < % (eg VATs) / $ Amount (eg Levies)>

    Rate: < X% (VATs) / $Y (Levies)>

    Charged on: <Total (eg for percentage tax) / Per Item (for levies like a Bed Tax at a hotel)>

    Tax Liability Account: <Drop down of liability Financial Accounts>

    Alternative Step 2: Financial Type

    On the Financial Type edit page, there would simply be a new section:

    Tax Rules: <Display Tax Rules already added and a (plus) icon to add another one>

    Alternative Step 3: Addressed by Alternative Step 2

    Alternative step 2 means that the Financial Type is made taxable by applying a "Tax Rule".

    Alternative Step 4: No need for change to core UI

    Just select a Financial Type as you do now - no need to programatically add (Taxable) into the drop down option as this will be up to the user to enter

    Alternative: Tax on Display Forms

    The amounts on the purchase form should be the total amount inclusive of all taxes.  Next to it, it can say (inclusive) and if you click on (inclusive) it could bring up a "Tool tip" style display of the amounts of different taxes included in the total amount.  The actual breakdown is visual clutter on purchasing forms, but should be displayed on receipts.


  5. Jul 04, 2013

    JoeMurray dit :

    Parvez, are you moving ahead with Andrew's useful suggestion regarding 'Tax Rules'?

  6. Feb 15, 2014

    Jamie Novick dit :

    JN - added comments about producing legal UK VAT invoices.

  7. May 18, 2016

    This scope of work mentions the ability to add multiple tax accounts to a financial type. Nether the LTS not the lates 4.7.7 versions allow multiple tax accounts to be added to a financial type.

    1. May 18, 2016

      JoeMurray dit :

      Heh Osvaldo,

      The core code is designed to _allow_ two taxes to be applied by an extension. You would need to fund the creation of such an extension still for a particular jurisdiction. Sorry about the bad news.

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.