Customising Shopfront

Adding Dynamic Fields to Receipts

Nick Clark
Updated

Our receipts are highly customisable, but this has makes showing some information slightly more difficult. Any information that is dynamic to the sale (such as invoice number, customer name, user name and more) must now be specified using a special piece of code.

 

Using Dynamic Fields

To add the dynamic field, you must first add a text field to a receipt:

Balance_not_updating_after_payment.gif

Once you've added the text component where you want, you can type in any of the fields for it to be automatically populated. Each field must be surrounded in curly brackets ("{" and "}") for it to be declared dynamic.

The fields that can be dynamic are currently:

Outlet Contact Details

Dynamic outlet details enable you to share receipt and statement templates across multiple outlets, while displaying the specific contact information for each individual outlet on the receipt or statement.

  • outlet.contact.addressCity: The City specified in the Outlet Settings page
  • outlet.contact.addressCountry: The Country specified in the Outlet Settings page
  • outlet.contact.addressPostcode: The Postcode specified in the Outlet Settings page
  • outlet.contact.addressState: The State specified in the Outlet Settings page
  • outlet.contact.addressStreet1: The street address specified under Street 1 in the Outlet Settings page,
  • outlet.contact.addressStreet2: The street address specified under Street 2 in the Outlet Settings page,
  • outlet.contact.addressSuburb: The Suburb specified in the Outlet Settings page,
  • outlet.contact.email: The Email Address specified in the Outlet Settings page
  • outlet.contact.facebook: The Facebook address provided in the Outlet Settings page
  • outlet.contact.fax: The Fax number provided in the Outlet Settings page
  • outlet.contact.mobile: The Mobile number provided in the Outlet Settings page
  • outlet.contact.phone: The Phone number provided in the Outlet Settings page
  • outlet.contact.twitter: The Twitter address provided in the Outlet Settings page
  • outlet.contact.website: The Website address provided in the Outlet Settings page
  • outlet.businessNumber: The ABN provided in the Outlet Settings page
  • outlet.name: The Outlet that the sale was completed at (this may not exist if the outlet or register has been deleted when reprinting a receipt - it will always exist at the time of sale),

For example, to add the outlet name to a Receipt or Statement template, use the placeholder {outlet.name}

Sale Details

  • invoiceNo: The invoice number (this will always exist),
  • completedAt: The time of the sale (this will always exist),
  • user.name: The user who completed the sale (this may not exist if the user was offline or the user has been deleted),
  • register.name: The register that the sale was completed at (this may not exist if the register has been deleted when reprinting a receipt - it will always exist at the time of sale),
  • customer.name: The first and last name of the customer (this will not exist if there is no customer attached to the sale),
  • customer.firstName: The first name of the customer (this will not exist if there is no customer attached to the sale),
  • customer.lastName: The last name of the customer (this will not exist if there is no customer attached to the sale),

 For example, to add the invoice number use the placeholder holder {invoiceNo}

 

Functions

We also support a limited number of functions that allow you to make your receipts really dynamic:

Coalesce:

This works the same way that many SQL languages use coalesce, it takes an unlimited amount of arguments and returns the first that is not null.

For example, when you have not specified a customer but still want the receipt to display "The Customer" you can use coalesce:

Customer: {coalesce(customer.name, "The Customer")}

This will output the following when no customer is specified:

Customer: The Customer

And it will output the following when the customer's name is "Stephen Strange":

Customer: Stephen Strange

 

Format:

This formats a date argument to a specific format, it takes the following arguments:

  • Date Time: The date time instance to format,
  • Format: The date and time format to use

For example, if you wish to display the date and time that the sale was completed in a long, easy to read format, you could use the format function:

Sale Completed At: {format(completedAt, "dddd, MMMM, Do YYYY, h:mm:ss a")}

This will display a date and time similar to:

Sale Completed At: Sunday, February 14th 2010, 3:25:50 pm

 

If:

This works similar to how most spreadsheet programs use "if", it takes three arguments:

  • Condition: The condition to meet,
  • When True: What to do when the condition is true,
  • When False: What to do when the condition is false

For example, if you wished to congratulate the person who had the 1000th sale, you can use the if function:

{if(invoiceNo = 1000, "Congratulations! You have completed the 1000th sale!", "Nope, not the 1000th sale")}

This will display the following if the invoice number is number 1000:

Congratulations! You have completed the 1000th sale!

And when the invoice number is number 123:

Nope, not the 1000th sale

 

Add:

This simply adds all arguments that are provided together, it takes an unlimited amount of arguments. For example, if you wished to add 10000 to each invoice number, you can use the add function:

Invoice Number: {add(invoiceNo, 10000)}

If the invoice number is number 42 it will output the following:

Invoice Number: 10042

 

Contains:

This allows you to check if a value contains another value (you'd use this inside an if function). It takes two arguments, the first is the haystack (what is being search) and the second is the needle (the thing to search).

{if(contains(customer.name, "Fred"), "Hi Fred", "You're not Fred!")}

If the customer's name contains Fred, it would output the following:

Hi Fred

 

Equal:

This checks that two values are equal (you'd use this inside an if function). It takes two arguments to compare and will ignore the type of the arguments (so 1 and "1" are the same).

{if(equal(customer.name, user.name), "You're selling to yourself!", "")}

If the customer's name is the same as the user's name you'll get the following output

You're selling to yourself!

 

Number Format:

This function formats a number to the format specified, the arguments are as follows:

  • value: The value to format,
  • prepend: What to prepend the value with (defaults to nothing),
  • append: What to append the value with (defaults to nothing),
  • decimal places: The amount of decimal places to format the number to (defaults to 2),
  • thousands separator: The separator to use between thousands (defaults to ","),
  • decimal separator: The separator to use between the whole number and any decimal places (defaults to ".")

So if you wanted to just format a number to two decimal places you can use the following:

{number_format(42)}

This will output:

42.00

If you wanted to format a value as currency (in AUD) you can use the following:

{number_format(42, "$") 

This will output:

$42.00

If you wanted to format a as currency (in EUR - German format) you can use the following:

{number_format(42, "", "€", 2, ".", ",")

 

Raw HTML

We also support specifying raw HTML in the text field, this allows you completely customise the receipts and "break out" of the receipt editor to completely generate custom receipts.

For example you could use the following to show an image when a customer is provided:

{if(customer.name, "<img src='your-image-url-here' />", ""}

This will show nothing if there is no customer, but if a customer is specified it will show the image provided.

 

{customer.code}
{customer.company}
{customer.name}
{customer.firstName}
{customer.lastName}

{customer.businessNumber}
{customer.birthday}
{customer.gender}
{customer.emails}
{customer.fax}
{customer.phone}
{customer.mobile}
{customer.website}
{customer.twitter}
{customer.facebook}

{customer.billing.addressStreet1}
{customer.billing.addressStreet2}
{customer.billing.addressSuburb}
{customer.billing.addressPostcode}
{customer.billing.addressCountry}
{customer.billing.addressState}
{customer.billing.region}

{customer.delivery.addressStreet1}
{customer.delivery.addressStreet2}
{customer.delivery.addressSuburb}
{customer.delivery.addressPostcode}
{customer.delivery.addressCountry}
{customer.delivery.addressState}
{customer.delivery.region}

{customer.invoiceMessage}
{customer.comments}
{orderReference}

{customer.customerGroup.name}
{customer.loyaltyEnabled}
{customer.loyaltyRate}
{customer.loyaltyPoints}
{customer.disablePromotions}
{customer.priceList.name}
{customer.specialPricing}
{customer.priceRule}
{customer.priceRuleAmount}
{customer.accountLimit}
{customer.currentOwing}