Lightrail Documentation (v2)

Download OpenAPI specification:Download

Lightrail Support: hello@lightrail.com

Introduction

Welcome to Lightrail. Lightrail is accessed through REST calls and JSON-encoded data. You can build in to the API using one of our libraries or directly with the REST/HTTP client of your choice.

You can test drive the API with a REST client like Insomnia or Postman. Download the OpenAPI spec using the download button above, import it, configure a test mode API key from Lightrail and start playing.

If you're just starting to learn about Lightrail start with the object model documentation.

Dates and Durations

All dates and durations are sent and received in ISO 8601 format.

Date format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example date: 2007-04-05T14:30:00.000Z

Duration format: PnYnMnDTnHnMnS

Example duration: P7DT12H

Filtering

Resources that may contain lots of entries (Contacts, Values, Programs, Transactions) have filters for retrieving a subset of the entries.

Some query filter properties support operators for more powerful filtering. The operator is specified after the property and a dot (eg: balance.ne for balance not equal to).

operator description
lt Less than (<).
lte Less than or equal to (<=).
gt Greater than (>).
gte Greater than or equal to (>=).
eq Equal to (==). This is the default where no operator is specified.
ne Not equal to (!=).
in Equals one of the members of a comma-separated list. Literal commas must be escaped (\,).
like Equal to with wildcard support. Percent signs (%) in the value are wild. This operator is only supported on string properties.
isNull Equal to null (true) or not equal to null (false).
orNull Allows other filters acting on the same property to also include results if the property is equal to null (true), or, not equal to null (false).

Examples

  1. List Contacts where email equals "mia.wallace@example.com" or "mia_wallace@example.com": https://api.lightrail.com/v2/contacts?email.in=mia.wallace@example.com,mia_wallace@example.com

  2. List Values where currency equals "USD" and balance greater than or equal to $10: https://api.lightrail.com/v2/values?currency=USD&balance.gte=1000

  3. List Contacts where email address is "like" %@gmail.com where % acts as a wild card (ie: ends with @gmail.com). https://api.lightrail.com/v2/contacts?email.like=%@gmail.com

  4. List Programs where endDate is greater than date or null (ie: filtering for non-expired). https://api.lightrail.com/v2/programs?endDate.gt=2019-11-08T12:00:00.000Z&endDate.orNull=true

Paging

Resources that may contain lots of entries (Contacts, Values, Programs) may not return all results in a single response. Instead they return a number of results limited by the limit query parameter.

Retrieving results after the first page means following links in the Link header. Here's an example Link header...

(all line-breaks are inserted here for clarity and don't exist in production)

Link:
  </v2/contacts?limit=100>;
    rel="first",
  </v2/contacts?limit=100&before=eyJpZCI6ImplZmYgaXMgYXdlc29tZSJ9>;
    rel="prev",
  </v2/contacts?limit=100&next=eyJpZCI6ImplbiBpcyBhd2Vzb21lIHRvbyJ9>;
    rel="next",
  </v2/contacts?limit=100&last=true>;
    rel="last"

This example has links to the first page, the previous page, the next page, and the last page. When already at the first page there will only be links to the next and last. When already at the last page there will only be links to the first and prev. If there are no results to page though or only one page there will not be any links.

It's important to follow the links in the Link header and not construct the URLs on your own.

Errors

Lightrail uses the following HTTP status codes to indicate an error:

code meaning
400 The request could not be understood. eg: JSON body could not be parsed.
401 Authentication missing.
403 The operation is not allowed for the given authentication.
404 The resource was not found. eg: There is no Contact for the given ID.
409 The operation could not be performed because of the state of the system. eg: There is not enough balance for a Transaction to complete.
422 The request was understood but has a logical problem. eg: Attempting to credit a negative amount. If using the stripe payment rail, most Stripe errors will result in a 422.
424 The request failed due to a failed third party dependency (such as an error calling Stripe). This can indicate that Lightrail and a third party are an inconsistent state. eg: While attempting to reverse a checkout Transaction with two Stripe charges, the first charge is refunded but the second refund fails. Refunds in Stripe cannot be undone which leaves the system in a state that it cannot automatically recover from. Note, this status code is extremely rare and represents a worst-case scenario for which some intervening action will be necessary.
429 Too many requests in a given amount of time.
500 Internal server error. Please contact us with details of your request and we'll look into it.

Lightrail errors contain a JSON body with the following properties:

property always present purpose
message yes English explanation of the error. This is for display purposes only as the explanation may be formatted or change between system updates.
statusCode yes The HTTP status code.
messageCode no A constant corresponding to the message. This can be used to take action in response to the error.
stripeError no When using the stripe rail: the full error response from Stripe in case of an error charging a credit card.

An example:

{
    "message": "Insufficient balance for the transaction.",
    "statusCode": 409,
    "messageCode": "InsufficientBalance"
}

Support

Contact us any time if you have any questions. We're here to help.

Authentication

Bearer

Lightrail authenticates your calls with an API key. You can retrieve your Lightrail API key from the Lightrail website.

Your API key carries many privileges, so keep it secure! Do not share it publicly, embed it in publicly assessible web pages or source code.

To use your API key in a request include in the following header:

Authorization: Bearer <API_KEY>
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "<API_KEY>"

Contacts

Contacts are the people or businesses who buy products or services from you. They're identified by a unique id, which typically corresponds to an existing identifier in your system.

Values can be attached to Contacts. All (applicable) Value attached to a Contact will be used in a checkout Transaction simply by specifying the Contact checking out.

Create a Contact

Authorizations:
Request Body schema: application/json
id
required
string

The ID you choose to represent the Contact. Two Contacts can't have the same ID, guaranteeing repeated calls won't create extra resources. We recommend not using email addresses as IDs because users can change email addresses but the ID can't be changed.

email
string

The Contact's email address.

firstName
string

The Contact's first name.

lastName
string

The Contact's last name.

metadata
object

Arbitrary data associated with the Contact.

Responses

Response Schema: application/json
createdBy
string

The ID of the user who created the Contact.

createdDate
string

Date when the Contact was created.

email
string

The Contact's email address.

firstName
string

The Contact's first name.

id
string

The ID you choose to represent the Contact.

lastName
string

The Contact's last name.

metadata
object

Arbitrary data associated with the Contact.

updatedDate
string

Date when the Contact was last updated.

Request samples

Content type
application/json
{
  • "id": "60b965da-e8a1-49c7-8abd-a11686662328",
  • "firstName": "Jeffrey",
  • "lastName": "Lebowski",
  • "email": "thedude@example.com",
  • "metadata":
    {
    }
}

Response samples

Content type
application/json
{
  • "id": "60b965da-e8a1-49c7-8abd-a11686662328",
  • "firstName": "Jeffrey",
  • "lastName": "Lebowski",
  • "email": "thedude@example.com",
  • "metadata":
    {
    },
  • "createdDate": "2020-09-17T16:55:59.000Z",
  • "updatedDate": "2020-09-17T16:55:59.000Z",
  • "createdBy": "user-c0e4bc89ec714e6199199e8322459e2e-TEST"
}

List Contacts

Authorizations:
query Parameters
email
string

Filter by email. This filter supports operators: lt, lte, gt, gte, eq, ne, like. See filtering for more information.

firstName
string

Filter by the firstName. This filter supports operators: lt, lte, gt, gte, eq, ne, like. See filtering for more information.

id
string

Filter by ID. This filter supports the operators eq, in. See filtering for more information.

lastName
string

Filter by the lastName. This filter supports operators: lt, lte, gt, gte, eq, ne, like. See filtering for more information.

limit
number <integer>

The max number of items to get.

valueId
string

Filter by Value ID. This filter supports operators: lt, lte, gt, gte, eq, ne, like. See filtering for more information.

Responses

Response Headers
Limit
string
Example: 100

The limit on the number of items returned.

MaxLimit
string
Example: 1000

The maximum limit available on this endpoint.

Link
string
Example: "<URL>; rel=\"first\", <URL>; rel=\"prev\", <URL>; rel=\"next\", <URL>; rel=\"last\""

Links to the first, previous, next and last pages in this paginated endpoint. See paging for more information.

Response Schema: application/json
Array ()
createdBy
string

The ID of the user who created the Contact.

createdDate
string

Date when the Contact was created.

email
string

The Contact's email address.

firstName
string

The Contact's first name.

id
string

The ID you choose to represent the Contact.

lastName
string

The Contact's last name.

metadata
object

Arbitrary data associated with the Contact.

updatedDate
string

Date when the Contact was last updated.

Response samples

Content type
application/json
[
  • {
    }
]

Get a Contact

Authorizations:
path Parameters
id
required
string

The ID of the Contact to get.

Responses

Response Schema: application/json
createdBy
string

The ID of the user who created the Contact.

createdDate
string

Date when the Contact was created.

email
string

The Contact's email address.

firstName
string

The Contact's first name.

id
string

The ID you choose to represent the Contact.

lastName
string

The Contact's last name.

metadata
object

Arbitrary data associated with the Contact.

updatedDate
string

Date when the Contact was last updated.

Response samples

Content type
application/json
{
  • "createdBy": "user-c0e4bc89ec714e6199199e8322459e2e-TEST",
  • "createdDate": "2020-08-26T18:04:44.000Z",