Laylo Partner SDK Documentation

Overview

Introduction

The Laylo Partner Node SDK allows you to pass your customers’ conversion events to Laylo. This is similar to using platforms such as Google Analytics to track events and conversions. With this conversion data, customers are able to better segment their fans for targeted messaging. For example, they can send a message to all fans that have signed up for a drop but not yet purchased a ticket - driving engaged and interested fans to the ticketing platform.

Usage

Installation

In your terminal run

npm install @laylo.com/partner

or

yarn add @laylo.com/partner

Configuration

Before you make a track call you need to configure your SDK instance. We recommend doing this where you set up other third party services and clients, soon after your server or lambda starts.

The id, accessKey, and secretKey arguments in the example below belong to you and not your customers. You can create as many API keys as you want and revoke them at your own discretion.

If you’d like to integrate a laylo pixel, please reach out to [email protected] to inquire about creating Partner API keys.

import laylo from "@laylo.com/partner";

laylo.config({
  id: "YOUR_LAYLO_USER_ID",
  accessKey: "YOUR_API_ACCESS_KEY",
  secretKey: "YOUR_API_SECRET_KEY",
  companyName: "YOUR_COMPANY_NAME",
});

Customer API Keys

Your customers need to be able to provide you with their Laylo API keys. They can create multiple API keys and revoke them as well. Within your platform they should be able to save their Laylo API key.

They can generate Laylo API keys in their API Keyring at https://laylo.com/settings?tab=Integrations.

You can also send them this link which contains documentation on how to generate a Laylo API key.

Creating a Conversion

Once you have a customer’s API key and an event that you wish to turn into a tracked conversion you will call the track method.

import laylo from "@laylo.com/partner";

await laylo.conversions.track({
  customerApiKey: "CUSTOMER_API_KEY", // *required* THIS IS NOT YOUR API KEY. THIS IS EACH OF OUR MUTUAL CUSTOMER'S LAYLO API KEY.
  action: "PURCHASE", // *required* one of ['PURCHASE', 'CHECK_IN', 'ADD_TO_CART']
  name: "ROSEBOWL_04_05_2025", // *required* an identifier that indicates what the fan has purchased (ideally human-readable)
  metadata: {
    currency: "USD",
    totalPrice: 100.01,
    city: "Los Angeles",
    state: "California",
    country: "USA",
    href: "https://tickets.me/Lakers-Celtics-Game-5",
    title: "Lakers Celtic Game 5 2024 Finals",
    // you can additional properties here
  },
  user: {
    phone: "+1234567890", // a phone number or email is required
    email: "[email protected]",
    smsMarketingConsent: true, // if the phone number isn't already opted in, this indicates you've received permission from the user to subscribe to customer updates
    emailMarketingConsent: true, // if the email address isn't already opted in, this indicates you've received permission from the user to subscribe to customer updates
    // you can add additional properties here
  },
  layloProductId: "PROD_123", // an optional laylo productId that helps the customer better track engagement. you will need to get this value from the customer and it can change depending on the conversion flow.
});

Preferred Practices

Naming and Filtering Conversions

Customers are able to filter and segment their fans based on actions they have taken. There are two levels to filtering.

First Filter (action)

The action sent with the laylo.conversions.track call can be filtered on. For example, action: "PURCHASE". This allows customers to send messages to all fans that have purchased a ticket. It also allows customers to send messages to all fans that have not purchased a ticket.

Second Filter (name)

The name sent with the laylo.conversions.track provides an additional filter for the customer. For example, they can message all fans that have purchased a ticket to the show at Madison Square Garden on April 5, 2025 by using name: "MSG - 04/05/2025".

The name should be specific to the event, merch, product, etc. that is purchased by the fan. It does not need to be unique for each fan or each customer. Multiple of your customers can have the conversion name MSG - 04/05/2025.

A human readable name is preferred over an ID. This is because the customer will see the name within the Laylo platform and should be able to easily identify them. The name can only contain letters, numbers, underscores, hyphens, forward slashes, and spaces.

User contact information

An email or phone number must be sent with the user object. This is how Laylo can tie a conversion to a specific fan. If both properties are sent with the track call then only the phone number will be used.

When using the user.phone property you must include the country code.

Line Items

If you are going to add line items to your track call then you will want to take two different approaches depending on if you are a ticketing platform or an eCommerce platform.

Ticketing

Be sure to include the name argument so that conversion names are prefixed with the event name. For example, the following track call will create two conversions for the fan with the names MSG_Parking_Pass and MSG_GA_Pass

laylo.conversions.track({
  customerApiKey: "CUSTOMER_API_KEY",
  action: "PURCHASE",
  name: "ROSEBOWL_04_05_2025",
  metadata: {
    currency: "USD",
  },
  user: {
    email: "[email protected]",
    emailMarketingConsent: true,
  },
  lineItems: [
    {
      name: "Parking Pass",
      quantity: 1,
      price: 10,
    },
    {
      name: "GA Pass",
      quantity: 2,
      price: 20,
    },
  ],
});

eCommerce

You don’t need to include the name argument at the top level of the track call. An eCommerce order is unlikely to need a prefix for each line item.. For example, the following track call will create two conversions for the fan with the names Tour_Poster and Vinyl.

laylo.conversions.track({
  customerApiKey: "CUSTOMER_API_KEY",
  action: "PURCHASE",
  metadata: {
    currency: "USD",
  },
  user: {
    email: "[email protected]",
    emailMarketingConsent: true,
  },
  lineItems: [
    {
      name: "Tour Poster",
      quantity: 1,
      price: 10,
    },
    {
      name: "Vinyl",
      quantity: 2,
      price: 20,
    },
  ],
});

Marketing Consent

Fans that have reached your platform through a Laylo RSVP are typically already opted in to the customer’s marketing consent. However, if you have a marketing consent checkbox on your platform it is highly recommended to send that information to Laylo. If they have agreed to marketing then add the following code to the track call. Be sure to check you are enabling marketing consent for the appropriate communication channel.

Email

emailMarketingConsent: true

llo.track("PURCHASE", "ROSEBOWL_04_05_2025",
  {
    currency: "USD",
	  totalPrice: 100.01,
    city: "Los Angeles",
    state: "California",
    country: "USA",
  },
  {
	  emal: "[email protected]",
	  emailMarketingConsent: true
  },
});

SMS (Phone number)

smsMarketingConsent: true

llo.track("PURCHASE", "ROSEBOWL_04_05_2025",
  {
    currency: "USD",
	  totalPrice: 100.01,
    city: "Los Angeles",
    state: "California",
    country: "USA",
  },
  {
	  phone: "+1234567890",
	  smsMarketingConsent: true
  },
});

We always adhere to the latest regulations so if you send a phone number we will send a confirmation text to the user before sending them any marketing messages.

Additional Metadata

You can send additional information about the conversion event or the user through the track call. This gives customers additional insight into their own fans and provides the opportunity to create better relationships with their fanbase.

Special Metadata

Some metadata properties are special and handled differently by Laylo. Including this data with a conversion provides our shared customer with a richer, more valuable experience. Current properties are:

• metadata.currency - The currency code (ISO 4217) if the conversion is a transaction with a price. Ex: USD, EUR, GBP, etc.
• metadata.totalPrice - The total price of the transaction. It must be a decimal number with no more than two decimal places (ex: 12.02, 5.00)
• metadata.href - The URL of the page that the conversion took place on
• metadata.title - The title of the page that the conversion took place on

TypeScript Types

laylo.track arguments

type TrackParams = {
  /** Categorize the action taken by the user. It can be one of the following: 'PURCHASE', 'STORE_PURCHASE' (for ecommerce platforms like Shopify), 'CHECK_IN', 'ADD_TO_CART' */
  action: "PURCHASE" | "STORE_PURCHASE" | "CHECK_IN" | "ADD_TO_CART";

  /** Give your event a recognizable name. It can only contain letters, numbers, underscores, hyphens, forward slashes, and spaces. The name does not need to be unique for each user action. For example 'Lakers vs Celtics - 10/05/2024` is a name that will allow customers to filter by that event. */
  name: string;

  /** Properties of the event. This is a freeform JSON object with a set of special properties. */
  metadata: Metadata;

  /** Properties of the user. Must include an email or a phone number. If both are
	included then phone number will take precedence. */
  user: User;

  /** This is your customer's Laylo API key that they create at https://laylo.com/settings?tab=Integrations. It should be securely stored in your backend and never exposed on the frontend. */
  customerApiKey: string;

  /** The Laylo product ID associated with the event. Optional, but recommended for better tracking. */
  layloProductId?: string;
};

Metadata

type Metadata = {
  /** The currency code (ISO 4217) if the conversion is a transaction with a price. Ex: USD, EUR, GBP, etc. */
  currency?: string;

  /** The total price of the transaction. It must be a decimal number with no more than two decimal places (ex: 12.02, 5.00)  */
  totalPrice?: string;

  /** The URL of the page where the conversion occurred */
  href?: string;

  /** The title of the page where the conversion occurred */
  title?: string;

  /** The city that the user is located in */
  city?: string;

  /** The state that the user is located in */
  state?: string;

  /** The country that the user is located in */
  country?: string;

  /** Add additional metadata about the event that you want to see on the event. */
  [key: string]: string | boolean | number;
};

User

type User = {
  /** Include the user's email or phone number. We recommend validating emails using the library 
	`email-validator` before sending them. */
  email?: string;

  /** Include the user's phone number or email. Must be a valid phone number with a country code. 
	`+13101234567`. We recommend validating phone numbers using the library `libphonenumber-js` before sending them. */
  phone?: string;

  /** If this is true then the user will be subscribed to your customer when they send Laylo texts. If you pass a phone number then the user will be sent a confirmation text. Ensure that you have provided the user with the proper terms, conditions, and policies. */
  smsMarketingConsent?: boolean;
  /** If this is true then the user will be subscribed to your customer when they send Laylo emails. Ensure that you have provided the user with the proper terms, conditions, and policies. */
  emailMarketingConsent?: boolean;

  /** Add additional metadata about the user that you want to see on the event. */
  [key: string]: string | boolean | number;
};

Conversion Examples

Purchasing a ticket

Performers and teams have identified this information as crucial to their success. They want a way to engage with fans that have attended events both pre-show and post-show. As well, being able to directly reach out to fans that have not yet purchased a ticket but have shown interest through a Laylo drop is a great way to close out the sales period.

import laylo from "@laylo.com/partner";

await laylo.conversions.track({
  customerApiKey: "123",
  action: "PURCHASE",
  name: "ROSEBOWL_04_05_2025",
  metadata: {
    currency: "USD",
    totalPrice: 100.01,
    city: "Los Angeles",
    state: "California",
    country: "USA",
    href: "https://tickets.me/lady-gaga-nyc",
    title: "Lady Gaga at the Rose Bowl",
  },
  user: {
    phone: "+1234567890",
    smsMarketingConsent: true,
  },
  layloProductId: "PROD_123",
});

Checking into a show

Passing a scanned ticket or check in conversion allows customers to interact with fans at a show. They can push special promotions to them, such as discounts off merch or third party promotions (free Bud Light for the next 20 minutes).

import laylo from "@laylo.com/partner";

await laylo.conversions.track({
  customerApiKey: "123",
  action: "CHECK_IN",
  name: "ROSEBOWL_04_05_2025",
  metadata: {
    city: "Los Angeles",
    state: "California",
    country: "USA",
  },
  user: {
    phone: "+1234567890",
    smsMarketingConsent: true,
  },
  layloProductId: "PROD_ABC",
});