Change Log

September 2020

New REST API Documentation

The documentation for API calls has moved to https://apidocs.lightrail.com with a new look and more examples.

The new documentation is generated from an OpenAPI 3 Specification file. This file can be opened in a REST client such as Insomnia or Postman to get a head start in experimenting with the API.

August 2020

Bigger Reports

Reports bigger than 10,000 rows can now be downloaded as a single report.

User Services
  • Support for multi-factor authentication (MFA) using authenticator app or mobile phone number (SMS).
  • Users can generate and download backup codes for multi-factor authentication (MFA).
  • Account-level security measures for all account users including; requiring multi-factor authentication (MFA), setting a maximum password age, and setting a maximum number of inactive days before an account is locked.
  • Users can update email address.
  • UI updates to improve visibility of the Live/Testing mode toggle.
  • Ability for users to belong to multiple accounts with a single email address.

June 2020

Whitespace handling

Properties that uniquely identify resources cannot be created or accessed with leading or trailing whitespace. This applies to: IDs, Currency code, and Value codes.

Special handling for Value codes: Codes cannot be created with leading or trailing whitespace. However, because codes are often entered manually for lookup or for charging in a transaction, as a convenience we will trim any leading/trailing whitespace from codes supplied in these situations.

Dropped TLS 1.1

The Lightrail API server has dropped support for TLS 1.1 as described in our February announcement.

April 2020


Webhooks released! Webhooks can notify your application when Lightrail events occur. They enable you to react to events and trigger additional workflows.

See webhooks in our docs to get started.

February 2020

Value Editing

Users can now update a Value’s start/expiry date from the web app.

Added Referral Program Documentation

See referral-programs in our API docs for more information.

Notice: Lightrail Dropping TLS 1.1

The Lightrail API server will be dropping support for TLS 1.1 on June 1st, 2020. All clients connecting to the server will require TLS 1.2 from that point.

What is TLS 1.1? TLS 1.1 is an outdated version of the protocol that provides security in HTTPS. It has a number of known weaknesses. Browsers have begun to show warnings when connecting to a server using this protocol and plan on dropping support for it entirely. Lightrail also needs to drop support for this protocol to ensure that your API calls are safe.

What do I need to do? Ensure that your platform making API calls to Lightrail supports TLS 1.2. Here are a couple of ways to test this:

  • If available, configure the minimum version of TLS on your end to TLS 1.2 and check that calls to Lightrail still succeed.
  • From your platform make a call to GET https://www.howsmyssl.com/a/check and log the results. The list of TLS versions your platform supports is listed in the body. This service is provided by https://www.howsmyssl.com/.

January 2020

Programs Toggling of "Active" and "Inactive"
  • Programs listing page now shows only "Active" Programs by default, with the ability to toggle to "Inactive" or "All"
  • Reports show Programs in the dropdown, segmented by "Active" and "Inactive"
  • When attaching new Value to Contacts, only "Active" Programs are available for new Values creation

December 2019

Discount Seller Liability

Support for Rules definition and Explanation in the Program create and edit forms as well as Generic Code creation.

November 2019

New List Filter Operators
  • Operator isNull to filter for null or not null properties.
  • Operator orNull. This enables filtering for an operator and additionally returning results if the property is null or not.
  • See filtering in our API docs for more information.
Discount Seller Liability
  • New property discountSellerLiabilityRule on Values and Programs succeeds discountSellerLiability (deprecated) to support a broader set of use cases.
  • Lightrail-client (JS) version 4.3.0 released to support discountSellerLiabilityRule.
New Rules Functions

Lightrail rules (balanceRule, redemptionRule, discountSellerLiabilityRule) have two new functions available: findLast() and findLastIndex().

October 2019


Values can now be uncanceled. In the web app find "Uncancel" in the Value Actions drop down. In the REST API send {canceled: false} to the Update Value endpoint.

Reverse, Capture and Void against Frozen Values

Error messaging on reversing, capture pending and void pending on transactions with frozen Values has been improved. The documentation has been clarified. Pending transactions with frozen Values cannot be captured, only voided. Transactions with frozen Values cannot be reversed. (Pending transactions with canceled Values can be captured or voided. Transactions with canceled Values can be reversed.)

September 2019

Values List

Added the ability to list Values by id

Change a Value’s Code

Users can now change the code on any Value that is not an attached Value. We also record `metadata` to track last updated info. When viewing an Attached Generic code, the web-app now looks up the "parent" code and displays it on that "child" code.

Safely Retry Stripe Charges

Safely retry Stripe charges in the face of card declined idempotent responses.

Null a Value's code

Support for setting a Value’s code to null

July 2019

  • Checkout transactions can be configured to forgive charges smaller than the Stripe min charge amount (allowing the transaction to go through). The amount forgiven is recorded in totals
  • The amount Lightrail thinks is Stripe’s min charge amount can be configured for rare cases where we don’t in advance what it is (due to differences between transaction currency and settlement currency)
Change Code & Generic Code
  • Users can no longer use the changeCode endpoint to change unique codes to generic codes and vice-versa (allowing it leads to weird state issues).
  • Fixes a subtle issue that could cause the generic code performance tab to look wrong. This occurred when the generic code used a balance to track liability.

Reports released in the V2 webapp! This makes it easy for you to create Transaction and Value reports yourself. Right now reports with up to 10,000 rows are supported.

Generic Codes

Generic codes, which can be used as publicly advertised promotion codes, are now more customizable.

You can now set a limit for how many times a contact can use the promotion directly on the generic code. You can also control how many contacts can attach the generic code, helping you better control a promotion's liability. For example, you can now create a generic code that'll give customers $5 off their next two purchases and limit it to the first 500 customers to attach the code.

These new options are available in the web-app and through the API (under the new Value property genericCodeOptions). It's also possible to update existing generic codes through the API.

Stripe Charge Handling

Released a new feature giving you a new way to handle checkouts that result in a Stripe charge too small to be processed. There’s a new property on the Stripe source labeled forgiveSubMinAmount that will forgive those small charges. Forgiven charges are tracked in the new totals property forgiven. As before you still have the ability to not forgive those charges and handle it some other way.

June 2019

  • You can now update genericCodeOptions through the API.
  • This gives a path for users to migrate existing legacy generic values (used attachGenericAsNewValue: true) to use the new improved generic code functionality.
  • API object property consistency improvements (genericCodeOptions only show up if isGenericCode: true).
  • DB migration, the property isGenericCode is always now true or false (can no longer be null).
Version update - v3.0.0
  • Support for new generic code functionality.
  • Adds detach contact method.
  • Removes delete Value. This is no longer possible through the API.
Stripe Params

Added more Stripe params that can be passed through to Stripe via checkout.

May 2019

Bug Fix

Fixed error handling on a few errors that were being caught and incorrectly passed on to the user.

Generic Code Program Updates
  • Makes the new version of generic codes more functional in programs with constraints.
  • If you define a program with balance or usesRemaining constraints, these properties will now correctly apply to generic code perContact.balance / perContact.usesRemaining.
Generic Code

Added a dedicated tab to Programs to allow users to see their Generic Codes quickly.

Generic Code - Soft Launch
  • Enables per-contact usage constraints on generic codes. Users can now define generic codes to give customers a promotion that can be used n times.
  • Improved total liability controls.
  • Auto-attach capabilities for new generic codes.
  • Existing generic codes (legacy attachGenericAsNewValue workaround and shared generic codes) function as is with improvements:
    • Contacts associated with a generic code are now properly listed when viewing a generic code.
    • Generic code stats tabs are now correct.

April 2019

Bug Fix

Fix for users not seeing all their programs in a Value attach dropdown.

March 2019

Bug Fix

Detail page breadcrumbs.

Reversing a transaction

Reversing a transaction that includes a partially refunded Stripe charge now succeeds.

Transaction Chain
  • Better visual insight into transactions
  • See the whole chain
  • Click through to the chained transaction
  • Void, capture pending, reverse transaction
Update Program, Detach Value & more
  • Ability to edit Programs
  • Detach Value from Contact
  • Added Horizontal Table Scrolling for tables with many columns
  • Login (and other email field inputs) fixes validation checking of email address

February 2019

Detach Value

Added ability to Detach a Value from a Contact

UI Updates and Fixes
  • Self Sign-up Added
  • Transaction page refresh
  • Url Encoding for stat calls
  • Large issuance whitescreen error
  • Create a contact through the webapp
  • Updates to attach values and contacts
  • Removed columns and reformatted status
V2 Support and Fix
  • v2 support
  • update dependency to fix vulnerability
Attach Contact & Value
  • Attaching a Value to a Contact
  • Attaching a Contact to a Value
Bug Fix

Fixed character encoding for url when using IDs with special characters.

January 2019

Program Creation

Basic Balance / Balance Rule Builder as well as Advanced Program creation

UI Updates
  • Added program column to the Values List
  • Added Contact ID to Edit Contact Form
  • Test Mode toggle update
Generic Codes Form
  • Create Generic Code Form
  • Updated Value Detail Layout for Generic Codes
Updates and Bug Fixes
  • Improved error handling for Stripe responses during checkout.
  • Improved error handling if the connection to a user’s connected Stripe account was disabled in Stripe.
  • Creating an issuance from a program that has a startDate but no endDate will now correctly create.
  • Also improved error handling regarding startDate and endDate on Program creation/update.
  • Creating a program with duplicate values in program.fixedInitialBalances and program.fixedInitialUsesRemaining now returns an error.
  • Added retry logic for duplicate codes during issuance creation.
Program Creation
  • Users can now create basic Programs
  • Programs can have Fixed, or Ranged balances or Balance Rules that define Values (eg. a value worth a discount of 10%)
Small Bug Fixes
  • Calling DELETE on a Program that doesn't exist now correctly 404s.
  • Fixed conflicting program parameter combinations (ie, can't set balanceRule and minInitialBalance etc) so that API returns an error. There were four different combinations that were fixed.
  • Programs query by name is now enabled.
  • Fixed an issue that occurred when creating Values from a Program that had a balanceRule.
Generic Code Attach Functionality
  • Generic code new attach functionality. Now, the default behaviour when a generic code is attached to a contact will allow the contact to use the code as long as the code is active.
  • This is a more intuitive model and doesn’t result in copies of code.
  • It also solves the problem where ambiguous users using the code directly in checkout can use the code multiple times while contacts who attach the code can only use it once.
  • The legacy functionality of creating a single use value is still useful and is accessible by setting attachGenericAsNewValue: true in the request.

December 2018

Transaction improvements for a better UX

Expanded the types of transactions available to include reverse, pending, capture, and void. Reversing a transaction reverses any balance changes, uses remaining changes, and Stripe charges. Reverse can be used in refund situations, restoring values to how they were before the original transaction, letting your customers make another purchase sooner.

A pending transaction is automatically voided unless it is captured. Pending transactions are useful when your payment flow includes other systems and actions. If something goes wrong or your customer does not complete the payment flow, Lightrail automatically voids the pending transaction after a time so that things aren’t left in a partial or unusual state indefinitely.

Version update - v2.0.0

Ruby client for V2 is published.

Widget Support

Faster responses for requests for the drop in gift card config

Attach New Value to Contact & Bugfix
  • Attach now available from Contact Detail page as well as Contact List action menu
  • Modal - New Value Form
  • urlEncoded ids for all detail page routes
  • Setting programId on new value
  • Fixed uses component from always outputting
  • Reverse transaction support
  • Pending create, pending capture, pending void support
  • Pending and reverse transactions handled in program stats
  • Pending/capture/void support
Balance Totals

Balance is total sum of users Redeemable Value instead of only those generated by the Drop-in Program.

Hot fix

Hot fix for Inactive/Active code

November 2018

Drop-in Config

Drop-in gift card configurability support.

Issuance Status

Users can now set whether the Values in an Issuance are active or inactive upon creation.

Contact & Issuance Management

Editing Contacts as well as Metadata input on Issuances

Emoji Support 😍

Emoji support added for Value codes and metadata β€οΈπŸŽ‰πŸ•

Program Statistics

The Lightrail web app now shows users how a program is performing. We’ve added a Performance tab to the Programs sections that surfaces such things as:

  • Total amounts redeemed and the redemption rate
  • Total and average Overspend
  • How many values have been used in a program
  • ... as well how many values are canceled, expired, and outstanding
Currency Management
  • Prompt to create currency
  • Currency List page (Account/Currencies)
  • Currency create, read, update
Drop-in Widget

Updated all instances of "Gift" to "Gift Card" to make the language more specific.

October 2018

Issuance Display Updates

Lets users see any distinguishing characteristics that will help them identify the right issuance.

  • Users can now name the Issuance
  • Users can add notes to the Issuance to help in identifying it
  • Cleaner unifying language around Issuances / Codes
Transactions Update

Transaction reverse + transaction chain

Value Creation
  • Values can’t be created with balance or redemption rules with syntax errors
  • Values and Programs can’t be patched into an inconsistent state
Transaction List / Detail
  • List page to view all transactions
  • Detail page displaying steps and full transactions json
Debit/Credit Transaction
  • Can now add or remove amounts against Values (creating transaction)
  • Debit/credit action can be done from the value list and details pages
Updated Value & Transaction Support
  • Transactions track the change in usesRemaining in Lightrail transaction steps
  • Can credit and debit usesRemaining
  • Attaching a Value with a generic code and balance creates a transaction (because balance is created)
  • Value stats return the correct initialBalance for Values created by attaching a generic code with balance
  • Credit, debit and transfer transactions return specific error codes when the Value is canceled, frozen or inactive
  • Cannot credit, debit, transfer against a Value before startDate or after endDate
Issuance Update
  • Quantity increased to 10,000, added uses remaining field, and better validation on inputs.
CSV Updates & Issuance Big Fix
  • Balances in CSV download now display with decimal places, metadata renders, and special character display support
  • Issuance bug fix - New Values created with balance of 0 will now display as $0.00 in CSV download
  • Removed deprecated properties valueRule and uses from the API.
Balance & Redemption Rule Support
  • Balance Rule placeholder with view popover
  • Redemption Rule View

September 2018


Checkout transactions with many Values processes faster.

Value Actions
  • activate/freeze/unfreeze/cancel/show full code, from the values list and details page
Value Actions
  • Value Events (Transaction History)
  • Transaction Detail expansion
Checkout Totals, Transaction Listing
  • Checkout totals has been updated. This adds clarity to how a transaction was paid for with details like paidLightrail and paidStripe. This also puts this data in a more queryable format to better allow us to calculate overspend.
  • List transactions by valueId now has its own endpoint /values/{id}/transactions.
  • Issuance Metadata overriding
Issuance & Value Updates
  • Issuance size limit increased to 10,000.
  • List endpoints limit has been increased to 10,000 for CSV exports (header: Accept: text/csv).
  • Frozen or cancelled Values can no longer be attached to a Contact.
Reports Page

Users can contact Lightrail to generate reports based on custom parameters.

August 2018

Global Search

New: Added the ability to search for Contacts, Values (id or code), Transactions, and Programs globally!

Value Actions
  • Users can activate, freeze, unfreeze and cancel value now on the Value Details Page
  • Provides a secondary confirmation step to display a Modal when a user clicks Activate or Cancel since this operation is one-way
  • When users confirm the Activate or Cancel the status badge on the update left updates

Checkout transaction improvement when many gift cards are available.

Tax, Value & Program Updates
  • Configurable tax rounding. Now supported bankers (HALF_EVEN) and standard (HALF_UP). The system defaults to bankers if none is provided.
  • Program minInitialBalance fix.
  • Value creation, no currency or program bug fix.
Issuance & Program Updates
  • View Fullcode
  • Program Issuance List page
  • Create Issuance
Date Sorting Defaults

Defaulting sorting on lists is now by date created descending.


Issuances now have a name property to match Programs. The name will be used as the name of the CSV download.

Drop-in Widget

Gift card purchase widget passes through above Stripe charge ID

July 2018

Version 2 Released! πŸŽ‰