Frequently Asked Questions - xTuple FAQ



If you are using the payment gateway, the reason could be that the charge was made on the same day as the refund attempt. According to the documentation, does not allow you to refund a transaction that was charged on the same day.  Around midnight, takes all of the transactions that occurred during that day and submits them to the bank for settlement.  After this process, the transaction is considered "settled".  You can only refund a transaction which has been previously settled.

Under the guidelines established by generally accepted accounting principles (GAAP), financial data —and by extension, financial reports—are organized according to accounting periods. Accounting periods create a pre-defined and repeatable structure for financial reporting. The accounting cycle itself depends on accounting periods to facilitate the (typically) monthly and also annual auditing and closing of the books. Accounting periods are usually defined as monthly, quarterly, and yearly time frames. Financial reports follow the structure of the accounting periods—and so you have monthly, quarterly, and annual reports. Ad hoc reporting outside the boundaries of the defined accounting periods is not generally supported.

If you are making journal entries across different companies, you are now forced to keep each company in balance and make your entries happen with standard inter-company accounting procedures. For each company you would create matching Due To/From accounts on the balance sheet. There are lots of ways to set this up but here is a quick example:

Lets assume you are only using the company segment and the account number

Company 01 would need an asset account - 01-1501 Due To/From Company 02
Company 02 would need an asset account - 02-1501 Due To/From Company 01

Now instead of one journal entry you make two, one journal entry per company. Say, for example, we posted some G&A expense to company 01 and need to move it to company 02.

Credit 01-6500 $500
Debit 01-1501 $500

Credit 02-1501 $500
Debit 02-6500 $500

If our inter-company (Due to/from) account started at $0 we would now see a $500 balance in the account for company 01 and a ($500) balance for company 02.

The inter-company account(s) must remain in balance at all times, no exceptions. Any entry made to an inter-company account requires that a corresponding entry be made to the other inter-company account immediately. Any individual using inter-company account must know that they are not allowed to leave their desk if the inter-company accounts are out of balance, no exceptions. Inter-company accounts can really get out of control if people are not careful.

You can use either a Misc. A/R Credit Memo or a Sales Order Credit Memo to issue tax credits to your customers. The following example describes how to do this using the Misc. Credit Memo (although, the steps are very similar for Sales Order Credit Memos):


1. You need to credit Customer ABC for $25 tax
2. Open Misc. Credit Memo screen
3. Enter $25 in "Amount" field
4. Open "Tax" link
5. Create a new Tax Adjustment for $25
6. Post Credit Memo
7. View credit in Tax History report
8. Later: Apply Credit Memo to Customer open item

Yes, beginning with xTuple ERP version 3.3.0 we added the ability to reverse (i.e., void) Cash Receipts from the Cash Receipts report screen, found under Accounting > Accounts Receivable > Reports > Cash Receipts. When you reverse a Cash Receipt, you also undo any applications made originally when the cash was applied.

After a Cash Receipt has been reversed, it returns to an unposted state. That means you can then make any changes to the unposted document before you post it again.

Keep in mind, this works only for Cash Receipts entered in or after xTuple ERP version 3.3.0. Cash Receipts entered prior to 3.3.0 cannot be voided in this way. Also, any Credit Memos or Customer Deposits created from the unapplied balance when the original Cash Receipt was posted will not be reversed when a Cash Receipt is voided. Instead, a misc. A/R Debit Memo will be created in the amount of the original unapplied balance.

One possible explanation for this is that the Basic Balance Sheet which ships with xTuple ERP is YTD. Therefore, the only way to balance it against the Basic Income Statement is to view the Income Statement as YTD, as well.

It's also possible you've customized your financial reports, and the profit calculations in each report definition don't match.

We recommend entering G/L Chart of Account opening balances using one of two possible methods described in the document Entering Opening Balances.

The process of closing Accounting Periods and Fiscal Years requires an understanding of several xTuple ERP configuration options. This topic is covered fully in the Closing Procedures document.

In that document you will look at General Ledger (G/L) Account Number settings and how they relate to Accounting Periods that are open and/or frozen. Next, you will see two scenarios based on different configurations of these settings. Finally, you will see important issues to consider before closing Accounting Periods and Fiscal Years.

Forward-updating carries the ending balance for an Accounting Period forward to the beginning balance of the next Accounting Period, continuing the process until the current Accounting Period is reached. Keep in mind that balances cannot be forward-updated into Periods that are in the future relative to the current Period.

Forwarding trial balances is discussed in the Closing Procedures document.


In order to forcefully disconnect a user from the database, you have to find the Process ID (pid) for the backend connection of that user. Each user connection to the database spawns a backend process for their connection. Once you know the pid for the process, you can kill the process. On unix the command would be "kill [pid]" while other OSes may have different ways to kill a process. In order to find the pid you can look at the pg_stat_activity table and the column procid should contain the number you need.

If you don't remember which version of PostgreSQL you're running, you can always find out with the following SQL statement:

select version();

This is easy to do if you're familiar with pgAdmin. Simply connect to your server with pgAdmin. Select one of your databases. Open the SQL editor tool. Paste in the above command. Then execute the query. Your PostgreSQL version will be displayed in the results window.

When using the PostBooks Installer to install xTuple ERP on a Mac, you may run into an issue if you have a previous instance of PostgreSQL running. If you get an error message during the installation that says:

"There has been an error. There is not enough shared memory. PostgreSQL component requires a minimum shared memory segment of 32MB. Please increase "shmmax" kernel parameter (in /etc/sysctl.conf) or close any other PostgreSQL instances before restarting installation."

You can use the Terminal application on Mac OS X to run commands to stop the database service. You'll give yourself Superuser privileges, then switch yourself to the postgres user, then stop the service.

  1. Make sure you've closed all connections to the postgres database, such as PGAdmin or xTuple.
  2. Go to Terminal (It's in Applications/Utilities)
  3. Type: sudo su -
  4. Enter the password you use to login to your Mac
  5. Type: cd /Applications/xTuple/postgresql/bin/ (assuming you installed xTuple in the default directory. If not, you'll need to change the path to where you installed it).
  6. Type: sudo -u postgres ./pg_ctl -D /Applications/xTuple/postgresql/data stop
  7. You can start up the database in the same way, using the start command: sudo -u postgres ./pg_ctl -D /Applications/xTuple/postgresql/data start

This issue was raised in our forum, and we thought we'd post a possible answer here. We have spoken with various users who encountered this error and discovered something in common with both. Both had prior installs of other Open Source solutions on their computer, prior to installing PostBooks. In both cases the the other product also installed an instance of PostgreSQL. It appears the two installations of Postgres are conflicting, and preventing the PostBooks installer from finishing the install. If you are done for the moment evaluating the other Postgres-powered application, try uninstalling it, and then running the PostBooks installer again.

If you are going to use credit card processing or if you're getting this message ERROR:  function decrypt(bytea, bytea, unknown) does not exist then you need to install pgcrypto. Pgcrypto is a library used for encrypting sensitive data. The pgcrypto software is a popular add-on package included with the PostgreSQL source code distribution. The pgcrypto module is used by our credit card encryption functionality.  Even if you are not processing credit cards, we still recommend that pgcrypto be installed. 

First, we need to locate the pgcrypto.sql file.  One typical path to this is:  /usr/local/pgsql/share/contrib/pgcrypto.sql

If it isn't there you can always search for the file.  You may need to perform the search as root:  find / | grep pgcrypto.sql (be patient, this takes awhile)  Or if you're on Windows just use the Windows file search.

Once you've located the file the next step is to install it.  The command to install pgcrypto onto your database is: psql -U mfgadmin NameOfDB < /wherever/the/file/is/pgcrypto.sql  Or if you prefer using pgAdmin, connect to the database you want to install pgcrypto and open/execute pgcrypto.sql through the SQL Editor.  It is also a good idea to install pgcrypto.sql on the template1 database.


If this is happening to you, check your Item masters for the Items in question. Make sure the "Fractional" option is selected for any Items which you plan to use in partial quantities. If that flag is not selected, then the costs for the Item will be rounded up to the next whole number. This upward rounding would explain your inflated costs.

Yes, there are several reports which provide historical tracking number information. Look under Inventory > Shipping > Reports > Shipments. All of the reports in this section include a tracking number column. If you entered a tracking number for an order when you shipped it, then that information will be shown in all of these reports.


To add a custom event to xTuple ERP's event notification system, you have to know a little SQL and PL/pgSQL, Postgres' procedural language, and you have to understand how xTuple stores the data you want to watch.

For example, let's say you want to be notified whenever the quantity on hand of an item drops below the reorder level of that item at a particular site. Here are the steps you need to follow:

  1. Find out where the quantity on hand information is stored. It turns out this is the itemsite_qtyonhand column of the itemsite table.
  2. Create a new event type. The event types are stored in the evnttype table, so
    INSERT INTO evnttype(evnttype_name, evnttype_descrip, evnttype_module)
                 VALUES ('QOHBelowReorderLvl', 'QOH dropped below reorder level', 'I/M');
  3. Create a new trigger function on the itemsite table that watches the itemsite_qtyonhand column (see below). Do not modify an existing trigger, since that might be changed during a later upgrade and your event notification will stop working.
  4. In the xTuple ERP application, open the Preferences window. On the Events tab, select the user who should be notified of the event, select the event type on the left side of the window, and turn on the event notification on the right side of the window.
  5. Finally, test all of this to make sure it works the way you expect.

Here is a sample definition of a quantity on hand trigger function and trigger. Note that it isn't enough to create the function. You also have to define the trigger itself, which tells Postgres when to call the function.

 -- if the trigger function was called because the parent table was updated in any way

   -- if the quantity on hand changed and the new qoh is below the reorder level for this itemsite
   IF (NEW.itemsite_qtyonhand <> OLD.itemsite_qtyonhand AND
       NEW.itemsite_qtyonhand < NEW.itemsite_reorderlevel) THEN

     -- insert one new event, represented by an evntlog record
     --            for every person set up (in the evntnot table)
     --                             at this site (warehous_id)
-- to hear about the QOHBelowReorderLevel event type INSERT INTO evntlog (evntlog_evnttime, evntlog_username, evntlog_evnttype_id, evntlog_ordtype, evntlog_ord_id, evntlog_warehous_id, evntlog_number) SELECT CURRENT_TIMESTAMP, evntnot_username, evnttype_id, 'I', NEW.itemsite_id, warehous_id, item_number FROM evntnot, evnttype, item, warehous WHERE ((evntnot_evnttype_id=evnttype_id) AND (evntnot_warehous_id=NEW.itemsite_warehous_id) AND (NEW.itemsite_item_id=item_id) AND (NEW.itemsite_warehous_id=warehous_id) AND (evnttype_name='QOHBelowReorderLvl') ); END IF; END IF; RETURN NEW; END; $$ LANGUAGE 'plpgsql'; ALTER FUNCTION _lowqohTrigger() OWNER TO admin;
DROP TRIGGER IF EXISTS lowqohTrigger ON itemsite;

Thanks to Sebastián Salgado for this example.


Each database used by your organization has various extensions associated with it. These extensions may be modules (e.g., CRM) or other free or commercial add-ons. For each extension there will be configuration options. In most cases, your system administrator will be responsible for configuring your extensions. However, anyone with the appropriate privileges may also configure extensions.

Hint: Configuring user permissions and other setup information is handled separately from the configuration of extensions.

Because non-Inventory Items, by defintion, do not have Item Sites, you cannot view receiving information for them on an individual Site basis. That's why you have to select the "All Sites" option on this report to see your non-Inventory activity.

If you are having trouble vouchering a Purchase Order because there are Returns logged against it, then you probably left out an important step: Creating a Credit Memo for the Return. To do this, go to the "Uninvoiced Receipts/Returns" report screen and right-click on the Return record. In the right-click menu is the option to create a Credit Memo for the Return. Once the Credit Memo has been created, you should be able to continue processing your Voucher. Later, you can apply the Credit Memo to an open Voucher.

xTuple Connect

Connect does not currently support SSL or TLS encryption for email sent over SMTP. There is an open feature request to add this support. And you can learn more about potential workarounds at the following link:

That error typically indicates there is either an incorrect mail server configuration or a network problem of some kind. Check the mail server Options in the Batch Manager menu. Also check your mail server and network routing to make sure all is in order.

System Administration

If you have recently upgraded your xTuple version and you find you can no longer print reports from xTuple (but you could before you upgraded), you may need to reinstall your print drivers. Another thing to check is your user profile. Try creating a new user profile and test whether you can print from that new user profile.

There have been reports that upgrading to Mac OS X 10.6 (Snow Leopard) can cause the postgres user to be deleted from the PostgreSQL server where your xTuple database is running. To resolve this problem, the postgres user must be recreated. You can read more here:

The older versions supported by xTuple will vary depending on the current shipping release of the product. To learn more, please visit xTuple's Supported Versions (and End of Life policy) page.

This situation can occur if you are using Enhanced Authentication as a method for encrypting user log in information--and if you installed 3.3 on the same PostgreSQL server instance (i.e., same port) as your old 3.2 database. The problem arises from changes made to user handling in xTuple ERP 3.3.

If this happens to you, there are two options to correct the situation:

1. Disable enhanced authentication and reset the password in either version. Only the passwords of users who logged into 3.3 using Enhanced Authentication will be affected.

2. Or just reset the password in 3.2, keeping Enhanced Authentication enabled in 3.3. Then don't log into 3.3 with that account again.

This situation would have been avoided if the best practices approach of only hosting one database on one PostgreSQL instance had been followed.

The likely reason for this problem is that your PostgreSQL server has not had the Group Role "xtrole" added to it. The "xtrole" Group Role is new in 3.3.0. You won't run into this problem if you're upgrading a 3.2.x database to 3.3.0. It only happens if you're loading a fresh 3.3.0 database from an xTuple backup file.

Here are the steps required to fix the problem via PgAdmin:

  1. Connect to the server where the database is located (e.g.,  with pgAdmin)
  2. Add a new Group Role called "xtrole" having all the same privileges as the "openmfg" role
  3. Explore the properties of the "openmfg" role and make sure "openmfg" is a member in the "xtrole" Group Role

Here is the SQL to create the xtrole group and add an existing admin user to it:

GRANT xtrole TO admin;

Here is the SQL to create the xtrole group, create the admin user and make the admin user a member of that group (use this for new installations)

IN GROUP xtrole;

That should be all you need to do. Now log in with your xTuple ERP client.

That's called CIDR notation. Here's a handly calculator for figuring out an appropriate value: You need to know a little about the network you're setting the server up on and a bit about subnetting. A client may need to allow various networks to connect - they may have several subnets, etc - each network from where you want to allow connections from needs to have an entry in the pg_hba.conf, or at least a rule that fits. is a catch-all - any address will match with that rule. But, suppose you have a remote office, with a fixed IP on their router - all traffic from inside the office goes out with the same WAN IP of that router, say the WAN IP is - that's a single address from a single device. So, on your postgres server where they are connecting to you would create a pg_hba.conf entry similar to: host all all md5 /32 is the same as ( 1 address) /24 is the same as (254 addresses) Also, keep in mind that the pg_hba.conf file is read top to bottom. As soon as Postgres finds a rule that allows access, it stops reading rules - so make sure your access rules make sense. You can do all sorts of interesting things with the pg_hba.conf. Read the comments at the top of that file.

The quick and dirty answer is you can right click and export from any list in the application. The more advanced option is to use the xTuple API.

You can read more about using the API to export from xTuple ERP in the docs section.

There are two methods for importing data into the database of xTuple ERP.

  • CSVimp
    First, xTuple offers a free application called CSVimp that is designed to import Comma Separated Value (CSV) files into the database for the xTuple Applications (The same tool works for PostBooks, Standard and Manufacturing Editions). You can download CSVimp from our SourceForge project site. And detailed instructions for using CSVimp are available in our documents section.
  • xTuple API
    The second method is to use the API. The goal of the xTuple Application Programmer Interface (API) is to make importing data directly into the database much safer and easier than it is going directly into the regular table structure. Our appoach is to allow users to create, access, and update xTuple documents using a special database schema that closely mirrors the graphical user interface (GUI). You can read more about using the API to import data into xTuple ERP in the docs section.
Web Integration

The Yahoo Store integration document has recently been updated. The most current version can be found online at:

Make sure you scroll down to the Installation Details section. In particular, there is a note on how to find the hidden directories on a Mac:

On the Mac, the lower-level folders are hidden by default; you won't see these in the Finder unless you make a modification. This site will help you with the Finder issue:

As for the Xalan commands, I recommend that you take the alternate path described in the document and use xlstproc, which is standard on a Mac. The commands for the import are described in step 8 (in the detailed instructions).

xTuple Demo

First of all, please be aware that there are two types of demos available: the Free Trial and the local demo.

Free Trial

When you registered for the Free Trial you should have received an email with the login information for the online demo. That email contains all the information you need, including your password, for both the Mobile Web client and the Desktop client.

For more information on logging in to your Free Trial databases, please see how do I log into xTuple PostBooks?

Local Demo

If you chose not to apply for an xTuple Free Trial account, you will need to follow the instructions for installing the xTuple database, which explains how to install your own PostgreSQL database server and restore the xTuple database.


If your company has a support contract with xTuple, you can reach the xTuple support team either by phone or by opening a support ticket on the xTuple community site. Each support contract with xTuple specifies two "named support contacts." The named support contacts are the people at your company who are eligible to contact the xTuple support team for help. If you are not a named support contact but still need help, you should pose your questions to the named support contacts at your company. Your named support contacts will either know the answers to your questions—or they will be able to contact the xTuple support team to help get you the assistance you need.

Note: Web-only support is included for xTuple Cloud customers and also customers who have purchased Commercial PostBooks. Web-only support allows for one named support contact per company.

Commercial support is available for xTuple products. Please see the support options page for more detailed information.

All xTuple ERP installations are eligible for XTN Services whether running Manufacturing Edition, Standard Edition or Postbooks.

xTuple Network offers 3 levels of service to help you manage your Upgrades, Backups and Database Optimization and Tuning.

- XTN Basic - xTuple performs the upgrades on your database at a mutually convenient time.  Upon publishing a new version, we create a sandbox for you to test the latest functionality, and you decide when you're ready to migrate to the next version.

- XTN Backup - includes database upgrades (above) and adds a nightly backup service 5 nights a week.  The backups are stored on your server, as well as in our data center.  This redundancy provides peace of mind that your critical business data are protected and available for restore in the case of a disaster - natural or otherwise.

- XTN Premium - includes the upgrade service and nightly backups, and adds database tuning and optimization.  For larger databases, we recommend this service which is an iterative process based on how particular installations utilize xTuple ERP functionality. 

xTuple stores a minimum of the 5 most recent backups plus one backup each week for a minimum of 1 year. Because of network related problems the most recent backups may not always be consecutive by day.


As of version 3.6.0, xTuple no longer supports the PowerPC Mac platform. Only the Intel Mac platform is supported. Prior versions of xTuple did support PowerPC Macs, but beginning with version 3.6.0 xTuple no longer supports PowerPC Macs.

This is a known issue related to changes made to xTuple Locales. Users have reported running into this problem during upgrades to xTuple version 3.2.1. In order to resolve this issue, please go to System > Master Information > Locales and follow these steps:

1. Open each Locale
2. SAVE each Locale
3. Restart the application

Performing these steps should resolve the problem.

We recommend entering G/L Chart of Account opening balances using one of two possible methods described in the document Entering Opening Balances.

Forward-updating carries the ending balance for an Accounting Period forward to the beginning balance of the next Accounting Period, continuing the process until the current Accounting Period is reached. Keep in mind that balances cannot be forward-updated into Periods that are in the future relative to the current Period.

Forwarding trial balances is discussed in the Closing Procedures document.