Kill Bill was designed to support merchants and their customers (user account, or also referred to as 'user' or 'account' in this documentation) across different countries. In order to support that, there are a lot of different aspects that need to be covered ranging from character sets, timezones, multiple currencies, locales, and the ability to support multiple languages for all customer-visible data (e.g. invoices).

In addition, these features must work independently for the various tenants: a given merchant assigned to a given Kill Bill tenant must be able to configure the system differently than another merchant in a separate tenant.

Timezones

Supporting multiple timezones comes into play when a user needs to interact with the system and then later when the system computes state for this user:

  • A user cancelling a subscription needs to provide a date (requested cancellation date). That date must be interpreted by the system in the user account timezone

  • Subsequently, when the system computes the next invoice for instance, it must include all the items for the period of time reflected by the invoice and as seen by the user.

An example would be a user creating a monthly subscription on January 1st 2015 but from a timezone in PST (UTC-8). The action will actually happen at a specific point in time such as 2015-01-02T04:00:00.000Z. The system must correctly understand that the provided date needs to be interpreted in the user timezone so that when the user receives its first invoice, he sees a billing period ranging from 2015-01-01 to 2015-02-01. If the user then decides to cancel his subscription on 2015-02-01, the system also needs to make sure this date is interpreted in the user timezone to avoid charging for an extra day; in that case the user only provides a date with no time (the API works that way because it is much simpler from the user point of view), and so the precise point in time when that cancellation happens needs to be in the 24 hours period of that specified day in the user timezone.

More information on the internals of date, you can refer to this blog post.

Multiple Currencies

The Kill Bill catalog allows you to specify amounts in different currencies. Each Kill Bill account needs to specify a currency that is used by the system when generating invoices (by looking up the amount of the specified plan for that currency), and that is also used at the time of making a payment. All the credits later generated for the account will also be in that currency.

The system also allows you to use a different currency at the time of making a payment by using a currency converter.

Language Translations

Kill Bill supports language translations. Thus, users can view catalog strings, invoices, emails as per the language specified in the user’s account.

Language translations can be achieved via locale and resource bundle.

When an account is created, a locale needs to be specified. (e.g. fr_FR). The locale is used for extracting localized resources. Locales are used in conjunction with resource bundles. A resource bundle is nothing but a set of files. Each file corresponds to a different locale and contains key-value pairs corresponding to language translations. So, for example, you can have a catalog resource bundle with files like CatalogTranslation_en_US.properties, CatalogTranslation_fr_FR.properties and so on that contain catalog translation strings.

The system allows you to configure the following resource bundles:

  • Catalog Resource Bundle: ability to translate specific catalog strings in different languages (e.g. American English Gold plan translated as Plan Or in French)

  • Text Translation Resource Bundles: arbitrary text strings in different languages that can then be used later when creating documents out of templates to ensure they are translated in the language matching the account. Text translation strings are used in:

    • Invoice templates: Can be used to customize HTML invoices generated by the system. You can read the Invoice Templates document to know more.

    • Email templates: Can be used to customize the emails sent to customers. You can read the Email Templates document to know more.

Based on the locale associated with the account, catalog strings, invoices, emails are generated using the appropriate resource bundle file.