Receipt Templates

Checkout's templates for Invoices, Orders, Purchase Orders, and Thermal Receipts can be customized to meet your needs. If you'd like to customize any of these forms, you'll need to know HTML, and have an HTML editor. TextMate and TextWrangler are great examples of a versatile editors.

We have a quick video that shows you how to make a change to the standard Invoice template to include the list price of each Product. If you’d like to, you can also download the custom template that was created in the video.

Edit Your Template

Changing the layout of your templates
To adjust the layout of your invoice and other printing templates (order, quote, purchase order and receipt), you'll need basic HTML and CSS knowledge. Furthermore, you'll need a copy of Checkout to fully test and preview your results.

To get started, first download a copy of the default Checkout template.

To be able to use this template you must be on Checkout 4.0.9

After downloading this file, doubleclick the 'Checkout.checkouttemplate.zip' file on your Desktop, the resulting file is called 'Checkout.checkouttemplate'. The templates file is a so called bundle, which is a special type of folder, that is shown by the Finder as a single file. To show it's contents, control-click the file and choose 'Show Package Contents...' from the contextual menu that appears.

You can edit the template files in your text editor of choice. If you use TextMate, you can simply drop the entire templates file on its icon to get a listing of all the individual template files in the bundle.

Installing and previewing your templates
To preview your modified template, launch Checkout and open the Example Store or login to a Checkout store as a manager. Then double-click your template file in the Finder. Checkout will offer to Install or Preview the template. If you use the 'Preview' option, Checkout will generate a preview of your custom template without installing it in your store database. This way, you can keep making changes to the different files in the template and switch back to Checkout periodically to see the results.

The list of previewed templates in Checkout's Template Manager interface is cleared every time you log out of your store, the original files on your hard disk will remain untouched. When you are satisfied with the look of your custom template, click 'Install Template' to store the template in your store database.

Contents of a template file
Checkout works with both normal printers and receipt printers. Checkout has four separate template HTML files ('Invoice.html', 'Order.html', 'PurchaseOrder.html' and 'Quote.html') for normal printers, and one template HTML file ('Receipt.html') for receipt printers. Additionally the default templates have one shared CSS file (style.css) that is used by all the different HTML files. You can optionally include an icon file ('icon.png', 100 by 100 pixels) in your custom template, this icon will then be used to represent your template in the Template Manager interface.

Structure of a template
The best way to get acquainted with the Checkout template format is by looking at the HTML files in the default Checkout template. In these files you will find several variables that Checkout replaces with actual data when you print or preview a template. These variables can recognized by the $ mark that's in front of them. Most variables represent textual or numeric data, some of them returns lists of items that Checkout can loop through. There is one special variable ('$format') that gives access to a range of different functions that alter the formatting of textual or numeric data.

In the following sections we will cover the normal variables first, after that an overview of the functionality of the '$format' variable is offered. Finally, we will discuss how to work with variables that represent lists of items, such as products and tax rates, as well as how to work with 'if' statements in your template.

Required elements
Four Section Dividers are found in all HTML files, except for the 'Receipt.html' file. These dividers are formatted as HTML comments and are used by Checkout to spread out large documents over multiple pages. If you do not include these comments in your own template HTML files, Checkout will not be able to preview or use your template.

Section Dividers
<!-- checkout:header --> - Start of the document header, must be above the <body> tag
<!-- checkout:content --> - Start of the product table, can be spread out over multiple pages
<!-- checkout:footer --> - End of the product table, start of the document footer
<!-- checkout:end --> - Must be before the closing </body> tag

Variables from the Checkout database
This section provides an overview of the variables you can use in your templates. Most variables can be used in each template but some are only available for use in specific templates, such as '$formatted_request_number', which represents the number of the Order an Invoice or Receipt was created from and therefore can only be used in Invoice and Receipt templates.

Store Variables
$storeName - The name of your store
$storeImageURL - Your store's logo, to be used in an <img> tag
$templateHeader - Your store address, as supplied in ‘Logo and store information’
$templateHeader - Your footer, as supplied in 'Logo and store information'
Generic Document Variables
$formattedNumber - The number of an Order/Quote/Invoice/Purchase Order
$date - Date the document was created
$totalPriceEx - Total price without tax
$totalTax - Total of all applied taxes
$totalPriceIn - Total price including tax
$employee.name - Name of the employee who initially created the document
$terminal - Terminal the document was created on (see below)
Invoice/Receipt-only Variables
$formatted_request_number - Number of the Order an Invoice/Receipt originated from
$date_request - Date the Order an Invoice/Receipt originated from was created
$paymentTotal - Total amount paid
$due - Total amount due
Purchase Order-only Variables
$completeTotalPriceEx - Total price excl. taxes (received and still on order)
$completeTotalTax - Total taxes (received and still on order)
$completeTotalPriceIn - Total price incl. taxes (received and still on order)
$outstandingTotalPriceEx - Total price excl. taxes still on order
$outstandingTotalTax - Total taxes still on order
$outstandingTotalPriceIn - Total price incl. taxes still on order
Customer Variables
$client.formattedName - Customer name and company name as shown in Checkout
$client.binding_metadata.name - Customer full name
$client.binding_metadata.firstname - Customer first name
$client.binding_metadata.middlename - Customer middle name or initial
$client.binding_metadata.lastname - Customer last name
$client.binding_metadata.company - Customer company name
$client.binding_metadata.address - Customer address
$client.binding_metadata.taxnumber - Customer tax number
$client.binding_metadata.phone - Customer phone number
$client.binding_metadata.mobile - Customer mobile phone number
$client.binding_metadata.email - Customer email address
Supplier Variables
$supplier.formattedName - Supplier company and contact name as shown in Checkout
$supplier.binding_metadata.name - Supplier contact person full name
$supplier.binding_metadata.company - Supplier company name
$supplier.binding_metadata.address - Supplier address
$supplier.binding_metadata.taxnumber - Supplier tax number
$supplier.binding_metadata.phone - Supplier phone number
$supplier.binding_metadata.mobile - Supplier mobile phone number
$supplier.binding_metadata.email - Supplier email address
Product Variables
$product.quantity - Amount of product ordered
$product.binding_metadata.barcode - Barcode of Product
$product.binding_metadata.code - Code of product
$product.binding_metadata.brand - Brand of product
$product.binding_metadata.description - Description of product
$product.discount_percentage - Amount of discount given on a product
$product.priceIn - Price of product including tax
$product.totalPriceIn - Total of product including tax
$product.priceEx - Price of product without tax
$product.totalPriceEx - Total of product without tax
Payment Variables (only in Invoice/Receipt)
$payment.payment.name - Payment method (for instance: ‘Cash’)
$payment.payment.amount - Paid amount
$payment.payment.terminal - Computer the payment was received on (see below)
Terminal Variables
$terminal.binding_metadata.number - Terminalcnumber
$terminal.binding_metadata.name - Terminal name
Tax Variables
$tax.name - Name of the tax
$tax.rate - Tax rate (in percents)
$totalTaxes[$tax] - Tax amount
Preference Variables
$storeImageAutoSize - Located in the ‘logo and store information’ sheet
$PrintProductDescriptions - Located in the the 'advanced options' sheet
$PrintProductsIncludingTax - Located in the the 'advanced options' sheet
$PrintCombinedTaxInTotals - Located in the the 'advanced options' sheet

Variables that represent lists
Below is a list of all the variables that return lists of data. To see how you can work with lists, please see Working with Lists.

List Variables
$products - List of all the products on a document
$totalTaxes - List of all the taxes applicable to a product or document
$payments - List of all the payments made on an Invoice/Receipt
$product.serials - List of all the serial numbers recorded for a product

Formatting text, money and dates
The $format variable is different from all other variables in a Checkout template. It is used to format text, numbers and dates in a variety of ways. $format can be used to let Checkout format database information such as a customer address for print as well as for more mundane tasks, such as rounding of monetary values and adding the appropriate currency symbol to them.

The way to use $format is as follows:

$format.FormatterType(Value)

FormatterType can be one of the formatter types listed in the table below this section and Value can be a Checkout template variable, as well as a quoted piece of text. Don't worry if this description seems overwhelming, some examples below will make the usage of $format more clear.

Formatter Types

Generic Formatters
$format.currency() - Formats a monetary amount for print
$format.string('Text') - Tries to translate 'Text' when Checkout is not running in English
$format.quantity() - Returns an integer of the number between brackets
$format.percentage() - Converts a rate (0 to 1) to a percentage (0% to 100%)
Metadata Formatters
$format.name() - Formats a binding_metadata.name (first or last name first as in store preferences)
$format.address() - Formats a binding_metadata.address, localized for the address' country
Date Formatters
$format.shortDate() - Short version of the date between brackets
$format.longDate() - Long version of the date between brackets
$format.onlyDate() - The date between brackets, without the time in hours and minutes
$format.onlyTime() - Just the time of the date between brackets

Formatting Examples
Below are some examples of how you would use $format in your Checkout templates.

$format.currency($totalPriceEx)

The $format.currency function returns a formatted string for any monetary amount you supply between the brackets, complete with currency symbol, decimal- and thousands-separators if applicable. The code snippet above will print as the total price excluding tax of the document you are printing.

$format.longDate($date)
$format.shortDate($date)
$format.onlyDate($date)

All of the above functions return a neatly formatted version of the date you supply within the brackets. The first two combine the date and time, the onlyDate version returns just a medium length version of the given date. To customize the way these dates appear, go to the 'Formats' tab of the 'International' pane in System Preferences.

$format.string('Invoice')

All of the words that are used in the default templates are wrapped in one of these $format.string() functions. This way, for example, when Checkout runs in German, it will automatically replace 'Invoice' with 'Rechnung'. When there is no suitable translation for a word, Checkout displays the original word. We recommend utilizing this same function around any label words you use in your own templates, especially when you intend to share or resell your templates to others. If we receive enough requests for a specific word, we'll add it to Checkout's dictionary of localized words. The dictionary of localized words is case sensitive, so where 'Invoice' is translated, 'invoice' may not.

Working with Lists
To work with document variables that represent a list of items, you can use a simple #for loop construction to repeat the same HTML code for each item in the list. A good example is the following code snippet from the invoice footer, which loops through all applicable taxes to print their names, rates and amounts:

#for tax in $totalTaxes
  <tr>
    <td>$tax.name ($tax.rate%):</td>
    <td class="price">$format.currency($totalTaxes[$tax])</td>
  </tr>
#end for

Make sure you end each #for loop with #end for to let Checkout know where the loopable HTML code ends.

If statements
Sometimes you will have to determine something to decide how a template will be displayed. A simple example is the following code snippet, where we first determine if a footer was supplied in the 'Logo and store information' settings.

#if $templateFooter
    <div id="store_footer">
    $templateFooter
    </div>
#end if

Checkout also provides variables that represent the preferences you set in the ‘Advanced options’ settings. You can use these in your template to determine if and how you to print specific information, such as combined tax rates instead of taxes specified per rate.

#if $PrintCombinedTaxInTotals
  <tr>
    <td>$format.string('Taxes'):</td>
    <td class="price">$format.currency($totalTax)</td>
  </tr>
#else
#for tax in $totalTaxes
  <tr>
    <td>$tax.name ($tax.rate%):</td>
    <td class="price">$format.currency($totalTaxes[$tax])</td>
  </tr>
#end for
#end if

If you are familiar with programming concepts like these, you can experiment some more with these functions. Otherwise, simply copy these sections from the default templates and adjust the formatting of the CSS document and change the values within them.

More Information
Checkout renders every template live when you print or create a pdf. The Checkout templating system is built on top of Cheetah, an open-source Python template engine. To learn more about the the Cheetah template engine and other functionality you can use in Checkout templates, please visit the Cheetah website.

The templates are finally rendered by WebKit, the same engine that powers Safari. Since Checkout waits until your templates have completed rendering, it's possible to insert images and other items (such as a banner from your website) that are loaded from the web during printing. One thing to keep in mind is that printing will take longer, especially if you have a slow internet connection. And please keep in mind that printing could fail altogether if the server you are trying to reach is not available.