Basic Configuration

Settings configured in Python files

If you followed the installation steps, you should have a basic store to start using. There are a number of places you might want to configure.

  1. In the (or file, there are a number of general Django settings. However, there are a few that are specific to Satchmo. These default Satchmo settings can be overridden by adding them to a SATCHMO_SETTINGS dictionary like this:

        'SHOP_BASE': '/shop',
        'MULTISHOP': False,
        'PRODUCT_SLUG': 'items',
        'SSL':  True,

Satchmo recognises the following keys in SATCHMO_SETTINGS:



Used as the prefix for your store. Don’t append a trailing slash ('/') - Satchmo does this for you. In the default setting, your store is located at If you would like to change this setting, this is the place to do it. If you would like your store to be at the root of the url, set this to "".





A boolean used to enable or disable an optimization for running multiple sites with independent carts from the same Satchmo instance. If enabled, Satchmo will patch Site.objects.get_current() to dynamically determine the current site by looking up the host in the request headers. Normally, you would have to create a separate settings file for each site, which in turn would require loading multiple copies of Satchmo into memory. This optimization can reduce the memory required to serve multiple sites in a memory constrained environment.



A list of custom newsletters.



A list of custom shipping modules outside of the standard Satchmo distribution.



A list of custom tax modules outside of the standard Satchmo distribution.


Cookie expiration time.



The prefix used for category urls; see satchmo_category and satchmo_category_index.



The prefix used for product urls; see satchmo_product.



Whether or not SSL should be enabled for the checkout modules.



Which document generation system to use. See Setting up document generation.

  1. In addition to the Satchmo specific settings, there are some Django settings you will want to make sure are properly set:

    • Make sure that your DATABASES['default']['ENGINE'] variable is also set correctly.

    • You should ensure that all of your paths are setup correctly. Key ones to look at are:

      • MEDIA_ROOT this is where product images and other uploadable will be stored
      • MEDIA_URL ‘/media/’
      • STATIC_ROOT directory for css, js and template images, where they are collected
      • STATIC_URL ‘/static/’
      • STATICFILES_DIRS additional directories where search the source static files
      • ADMIN_MEDIA_PREFIX (obsoleted with Django 1.4)

    Satchmo uses for media files and destination static files different directories, as it is required by Django, but the source directories are for backward compatibility the same: However directories can be easy set different now and it is better for the future.

Changing the L10N Settings

Satchmo supports a setting L10N_SETTINGS that can be defined in your store’s file. To configure the currency format and other internationalization options. The example below would configure the Euro:

  'currency_formats' : {
     'EURO' : {'symbol': u'€', 'positive' : u"€%(val)0.2f", 'negative': u"€(%(val)0.2f)",
               'decimal' : ','},
  'default_currency' : 'EURO',
  'show_admin_translations': False,
  'allow_translation_choice': False,

Satchmo recognises the following keys in L10N_SETTINGS:


The default currency type to display.



Enable or disable the use of the translation options in the admin.



Enable or disable the translation section for the store user.

The L10N_SETTINGS variable also allows you to control whether or not translation fields should be displayed in the admin. In the example above, they will be disabled. The default is True

Setting up document generation

Satchmo is able to generate a various range of documents that generally need to be printed on plain old paper or on an equivalent electronic format (such as PDF).

Examples of these documents are invoices, packing slips and shipping labels (although the system can be adapted to much more than this).

For new projects, Satchmo renders these documents as normal HTML pages, which have been slightly optimized for direct printing (i.e. from the browser).

Should this not be enough for you, Satchmo also includes two (optional) ways to export said documents in PDF: one based on trml2pdf and the other based on _wkhtmltopdf.

Which system to use is controlled by the 'DOCUMENT_CONVERTER' key within the SATCHMO_SETTINGS dictionary, which should contain the full dotted path of the document converter to use.


wkhtmltopdf is a program that contains a statically compiled, headless WebKit rendering engine (which is the basis of succesful browsers such as Safari, Google Chrome, and the default browsers on the two most popular mobile platforms).

Installing it is as simple as downloading and unzipping the release for the platform you are using. After doing that, keep note of the directory where you have unzipped the release, and then enable it in your settings file.

To do the latter, set the 'DOCUMENT_CONVERTER' key within SATCHMO_SETTINGS dictionary to 'shipping.views.WKHTMLDocument'. Then you must tell Satchmo where the wkhtmltopdf binary can be found, by adding a 'WKHTML2PDF_BINARIES' key in the dictionary, whose value is another dictionary where the keys are the operating system categories as reported by sys.platform and the values are the absolute paths to the corresponding wkhtmltopdf binary.


You are not required to fill in a key for each platform: the key of the platform you are on is sufficient.

The values for the keys can be obtained by looking at the documentation for the core module sys, but here is a quick, non authoritative and incomplete list:

  • linux2 for Linux (linux on Python 3.3 and above)
  • darwin for Mac OS X
  • win32 for Windows

Therefore, if you are on a Linux machine you will do:

    'DOCUMENT_CONVERTER': 'shipping.views.WKHTMLDocument',
        'linux2': '/path/to/wkhtmltopdf-i386'

While on Mac OS X you will do:

    'DOCUMENT_CONVERTER': 'shipping.views.WKHTMLDocument',
        'darwin': '/path/to/wkhtmltopdf'


If you wish to use trml2pdf, you must first install Reportlab (based on the description for your OS here) and then trml2pdf itself:

pip install

Then you must set the 'DOCUMENT_CONVERTER' key within SATCHMO_SETTINGS dictionary to 'shipping.views.TRMLDocument'.

Customizing templates

If you wish to customize templates, keep in mind that they are located in shop/docs/html within the shop application for HTML templates (used by the default HTML generator, and by the wkhtmltopdf one) and within shop/docs/rml for the trml2pdf ones.

Developing your own

If you wish to develop your own document converter, take a look at shipping.views and implement a class with the same methods as HTMLDocument.

You will then be able to activate it by setting 'DOCUMENT_CONVERTER' to your class full dotted name (e.g. 'my.module.converter.MyDocument)


If you use a unicode character, you’ll need to have an encoding at the top of your file:

# -*- coding: UTF-8 -*-

Settings configured via Django’s admin interface

The majority of the store configuration is done through the admin interface. This can be accessed from the main admin page (usually at /admin/) via the Admin ‣ Edit Site Settings link. It is also usually available at the URL /settings/.

All of the configuration settings have detailed help notes. They also default to sensible configurations so your initial store should work fine without changing any values.

Base Settings

These items are used for general store configuration and include:

  • Account verification options
  • Default currency symbol
  • Enable/disable product ratings
  • Controlling display of featured products
  • Controlling quality of thumbnail creating
  • Enabling sending of html formatted emails

Google Settings

This section allows you to enable or disable google analytics and conversion tracking for adwords.

Payment Settings

Satchmo can handle multiple ways of accepting payment. By default, you have a dummy processor that does nothing but accept payments. Obviously, you’ll want to enable one of the other modules before going live.

Each payment module will have it’s own configuration items. These items apply universally to all payment modules.

  • Accept real payments
  • Allow URL access for cron rebilling of subscriptions
  • Force ship to and bill to countries to match during checkout
  • Cron passkey to allow subscription rebilling


After saving changes to your payment processor, you will need to restart your server for the changes to take effect.

Product Settings

Before you use any of the products, you need to make sure the appropriate products are added to your INSTALLED_APPS.

In this section you can also configure:

  • Allowing checkout with 0 inventory
  • Using Akismet for comment spam prevention
  • Number of recent items displayed
  • Measurement system
  • Number of featured items
  • Random display of featured products
  • Protected directory to be used for downloadable products
  • Specific directory where images should be uploaded

Shipping Settings

This section allows you to choose which shipping modules you want to make available to users when they check out.

Once you select the modules you would like to use, you will be given an option to enter any additional information required for that module.

Tax Settings

Satchmo allows different tax configurations. This section allows you to choose the active tax module and configure it for your store.


Satchmo has two methods for handling newsletter subscriptions. By default, you have an “ignore it” processor enabled. To enable handling, first add "satchmo.newsletter" to your list of installed modules in your settings file.

Next, choose the way you want to handle the subscriptions. Currently we have two working newsletter plugins:

  • satchmo.newsletter.simple - This just tracks subscriptions in a database table for your querying pleasure. You can then export that list to whatever mailing manager you want to use.
  • satchmo.newsletter.mailman - This is an integration module which works with Gnu Mailman ( This is particularly convenient if you have a Cpanel VPS system, since Mailman is installed by default on most such systems. To use this, you need to make sure Mailman is on your PYTHONPATH and you should have already set up a mailing list as an announce-only list ( You’ll need to enter the name of the list in your local settings file.


SSL Security can be set on any url in your store. In order for SSL to work, make sure that it is enabled in the middleware section of your


In order to support a fully encrypted page, you also need to make sure you provide a secure url for the media. This url will automatically be used in pages served by SSL, but only if you specify it in your


Then, enable it for the specific urls you would like to be protected by adding {'SSL': True} to each url. Here’s an example which would enable SSL for login:

(r'^accounts/login/$', 'login', {'SSL': True, 'template_name': 'login.html'}, 'satchmo_login'),

SSL for Payments works slightly differently. The are controlled by the Satchmo setting described above. To have all checkout pages enabled for SSL, just set SSL:True in your Satchmo settings.

Disabling the Live Settings System

Once your store is live, you may want to disable the admin ability to edit the site configuration. To do this, edit your file and add a new entry LIVESETTINGS_OPTIONS with the settings you want to lock into place. The easiest way to get it is by the URL

The LIVESETTINGS_OPTIONS must be formatted as follows:

    1 : {
        'DB' : False,   # or True for use db and ignore these settings
        'SETTINGS' : {
            'GROUPKEY' : {
                'KEY' : val,
                'KEY2' : val,
                # ...

            'GROUPKEY2' : {
                'KEY' : val,
                'KEY2' : val,
                # ...

            # ...

    # ...

In the settings dict above, the 1 is a site index, allowing you to have different settings for different sites. The val entries must exactly match the format stored in the database for a setting. For example, do not use a literal True or an integer, it needs to be the string representation of them.

If DB is False, then editting the settings via the admin will be disabled. All configuration must then be done through the settings file.

The easiest way to do this is to query the database for livesettings_setting and livesettings_longsetting, and convert to a Python dictionary manually.

Store Configuration

The final configuration option that is available is configuring which Countries you would like to ship to. This option is available through the Admin interface through Admin ‣ Shop ‣ Store Configuration. It is typically accessed through the URL /admin/shop/config

This section allows you to fill in store address and basic demographic information that is used throughout Satchmo. The Shipping Countries section will allow you to configure:

  • Whether or not to ship only within 1 country
  • The Default Country to ship to
  • All Countries which may be chosen during the checkout process

If you choose to allow shipping to multiple countries, the checkout process will automatically populate valid states based on the selected country.