Installation on a custom store

Before you start

In order for an integration with LoyaltyLion to be possible, there are a few key concepts and behaviours that your ecommerce store must support.

Customer identity

You must have a customer account system with a single notion of customer identity.

Customers don’t sign up for a separate “loyalty account” with the loyalty program - your store is responsible for their account membership status, and having an account with your store is equivalent to being enrolled in the loyalty program.

A good choice for this identity is the row ID associated with a customer’s record in your database, but it can be anything - as long as it’s unique per customer and doesn’t change.

You’ll use this throughout as the customer_id field for the customer - for example, when submitting orders. This is how we reconcile all their activity with a single loyalty program membership.

Discount vouchers

Your checkout must support single-use fixed discount voucher codes (for example, $5 off), as these form the basic rewards available from your loyalty program.

You must be able to bulk pre-generate these voucher codes for import into LoyaltyLion (so we can issue them to your customers).

When a customer claims a reward in exchange for points, we issue one of these pre-generated voucher codes for use in your checkout. We don’t implement the behaviour of those codes - that’s fully up to your store or ecommerce platform’s checkout.

Integration points

To complete an integration with LoyaltyLion, you need to cover four core integration points:

• Tell us when customers create an account with your store
• Load the LoyaltyLion SDK and customer UI
• Tell us when orders are placed, paid, refunded and cancelled
• Create a reward and import voucher codes

On top of this, you can offer extra loyalty program features with:

• Referrals
• Custom rewards
• Custom rules
• More advanced UI customisation

Customer lifecycle

When a customer signs up for an account with your store, you should submit a $signup event via the LoyaltyLion API. This tells us that the customer has upgraded from a guest account to a full membership, and it lets us give them points for signing up if you have that rule enabled.

See the activities endpoint for exact details on the payload to submit.

If a customer requests to leave your loyalty program, you can submit a request to our support team to delete their account and personal information in line with GDPR.

Order lifecycle

When an order is placed, edited, paid, refunded, or cancelled, you should tell us via the orders endpoints.

• The merchant_id field is the ID of the order within your system
• The customer_id field is your customer identity
• The discount_codes field should contain all discount codes used with this order. Vouchers previously issued as rewards are marked as used within our system, and any unknown vouchers are ignored.

Load the LoyaltyLion SDK and customer UI

The LoyaltyLion SDK gives you tools to display a loyalty program UI to your customers.

To use it, you’ll need to:

• Install the SDK snippet on all pages on your store
• Authenticate your customers with a server-side generated HMAC based on your customer identity
• Initialize the SDK, using that HMAC when a customer is logged in

Once the core SDK is installed and customers are authenticated, you can begin deeper customisation by adding UI components, like embedding a loyalty panel to your store.

Add rewards and import voucher codes

The last step is to set up some rewards for your customers to claim.

You should:

• Create a new reward
• In your store backend, create at least 500 unique voucher codes for use with that reward & import them into the reward you’ve created in LoyaltyLion
• Validate that you’ve created working codes on your store by claiming a reward yourself and attempting to use it in your checkout.