Overview
This document will provide instructions on implementing Swell on a generic / custom platform.
There are a handful of required implementation steps to get a minimal set of Swell Loyalty features running on a generic platform. Once the bare minimum is setup there will be additional implementation steps depending on the exact features you wish to utilize in your program.
Swell JS SDK
The first step in the implementation process will be to add the Swell JS SDK to your website. This typically gets added either in your <head></head> tag or at the bottom of your layout before your </body> tag. You can find your unique javascript URL in the /settings page of your Swell admin.
The snippet will look like this:
The Swell JS SDK will help power all of the loyalty, referral, and email capture functionality on your website. By adding this snippet and configuring your Swell Admin you could start using the Email Capture Tool out of the box without any additional work. Important to note that you will not be able to reward customer's a coupon for completing the Newsletter Signup campaign without creating and uploading coupon codes explained in the Coupon Creation & Upload step of implementation.
Identifying Logged In Customer
In order to know who is completing actions on your storefront we need to know who the current user is. Typically we identify a customer using their email address and "third party id" which is usually the id you use for them in your database.
The simplest way to identify the logged in customer is using a hidden <div> tag in your layout. On page load our JS SDK will scan the DOM for an element with an id of "swell-customer-identification" and if found it expects the logged in customer's information to be stored as data attributes on the element.
An example written using liquid templating would look like this:
Note: The data-tags attribute should be a JSON string representing an array of string tags. For example, if the customer was tagged "VIP" and "wholesale" you would want data-tags="['VIP','wholesale']"
Once you have identified the logged in customer you will now be able to utilize all of the non-spend based campaigns. This includes the following campaigns: Instagram Follow, Twitter Follow, Twitter Tweet, Twitter Retweet, Facebook Page Visit, Facebook Share, Happy Birthday Campaign, Code Entry Campaign, Yotpo Review, Read Content, and Custom Action.
Coupon Creation & Upload
Now that your customers can earn points we need a way for them to redeem those points for discounts. The most common way to achieve that is by using coupon codes. In your platform you will need to create bulk coupon codes for each type of reward you want to offer. For example, if you want to offer a 10% Off coupon code for completing the Newsletter Signup and the ability to redeem points for either a $5 Off, $10 Off, and a $25 Off coupon code then you will need to make sure to create bulk coupon codes for each one of these reward options.
Once these codes are created you can make sure to format them into a text file where there is one code per line and then upload the codes to their respective coupon in the Swell "Spending Points" section. It's up to you how many to upload per coupon but we would recommend at least a few thousand to get started.
Once you have coupon codes uploaded you can now allow your customers to earn them for completing a campaign or for redeeming points. You could even implement a redemption widget at checkout to automatically apply the code to the customer's order. Please see our implementation guide for more information about these features.
Order Data
If you would like to use any of the spend based campaigns or the referral program you will need to send Swell order data via our API. How much information you include depends on what features you want to use as part of your spend based campaigns. If you just want relatively simple points for purchases based on amount spent or number of purchases then you'll only need to provide just the required attributes. If you want to get more sophisticated and restrict certain campaigns to certain products or product collections then you'll have to include information about what products were purchased.
Create Order
POST https://app.swellrewards.com/api/v2/orders
Send a new order to Swell to be processed by active campaigns
Query Parameters
guid
string
The guid for your Swell account. Can be found in /settings section of your admin.
api_key
string
The api_key for your Swell account. Can be found in /settings section of your admin.
Request Body
item.vendor
string
The vendor / manufacturer of the product.
item.type
string
A category or product type, can be used in filtering for eligibility.
item.collections
string
A comma separated list of all the collections or tags that this product belongs to.
item.price_cents
integer
The total price of this item (for 1 quantity) in cents.
item.quantity
integer
The quantity of this product purchased by the customer in this order.
item.name
string
A customer facing name for the product.
item.id
string
An identifier that uniquely identifies this product in your database.
items
array
An array of items purchased. Required if you want to run a campaign that requires certain products or collections to be purchased.
discount_amount_cents
integer
The total amount the customer saved using a discount in cents. This is used to keep track of the costs of the discounts you give out.
user_agent
string
The user agent of the customer's browser when they placed the order. This is required for the referral program to work.
ip_address
string
The ip address of the customer when they placed the order. This is required for referral program to work.
coupon_code
string
A comma separated list of coupon codes used on this order.
created_at
string
A timestamp describing when this order was placed. Defaults to the current time if not provided.
status
string
Sometimes you might want to separate the removal of points for using a discount code at checkout and the rewarding of points for the order. We will use an order status to determine what we should do.
order_id
integer
An identifier that uniquely identifies the order in your database.
currency_code
string
The currency used (e.g. 'USD')
total_amount_cents
integer
The total amount the customer spent in cents.
customer_email
string
The email address of the customer who placed the order.
It's worth explaining the status field in a little more detail. In order to understand why it matters you will need to understand a little bit more about how our redemption process works. When a customer wants to redeem their points there are two main ways you can have this work:
1) Convert the points explicitly to a coupon code that you give to the customer to use at checkout. In this version, we will remove the points from their account immediately because they receive the coupon code in exchange and can use it whenever they would like. There's no use for the status field in this version because you can just send us the order when you are ready for it to be processed by the active campaigns.
2) Convert the points to a discount at checkout. You are still converting to a coupon code but the difference is that the customer is not explicitly aware of the coupon code. We typically recommend implementing this in a way that the coupon code automatically gets applied to the current cart after a successful redemption. In this version, we do not remove the points from the customer's account until after the purchase is made. The reason we do this is that the customer might redeem points at checkout and either change their mind about which redemption option they want to use or not go through with checkout at all. If we took away the points immediately then the customer would not be able to change their mind and they would not have access to the discount code. In order to avoid this bad experience and likely customer support issue we wait to remove points until after they checkout. You might also want to delay the rewarding of points until the order is fulfilled or some other state other than immediately after purchase. In this case you can use the status attribute to differentiate between "paid" (when we will remove the points used for the discount at checkout) and "awarded" (when we will process the purchase through the active campaigns). You can use whatever statuses you would like, you will just have to specify them in the Swell admin /settings section.
Refund Data
If you would like to remove points or give points back for points used at checkout for refunded orders then you will need to send us refund data. Similar to order data, if you are using product specific requirements or restrictions for campaigns then you will also have to include specific item information along with the required refund data.
Create Refund
POST https://app.swellrewards.com/api/v2/refunds
Send a new refund to the Swell API to adjust previously processed order.
Query Parameters
guid
string
The guid for your Swell account. Can be found in the /settings section of your admin.
api_key
string
The api_key for your Swell account. Can be found in the /settings section of your admin.
Request Body
item.quantity
integer
The quantity of this item refunded. This cannot exceed the quantity purchased that was set during the creation of the order.
item.id
string
An identifier that uniquely identifies this line item or product in your system. It must match the item.id passed in during the creation of the order.
items
array
An array of items refunded.
total_amount_cents
integer
The total amount the customer was refunded in cents.
order_id
string
The identifier used to uniquely identify the order in your system. It must match the order_id used when the order was created initially.
id
string
An unique identifier used to identify this refund in your system. If you don't track these explicitly in your database then we will create one internally.
Customer Data
If you would like to reward for account creation or restrict your program by certain customer tags or collections then you will have to send us customer data.
Create or update customer
POST https://app.swellrewards.com/api/v2/customers
Query Parameters
guid
string
The guid for your Swell account. Can be found in the /settings section of your admin.
api_key
string
The api_key for your Swell account. Can be found in the /settings section of your admin.
Request Body
tags
string
A comma separated list of tags (or collections) this customer belongs to. Note: This will overwrite existing tags.
last_name
string
The last name of this customer.
first_name
string
The first name of this customer.
string
The email address used by this customer.
id
string
The identifier used to uniquely identify a customer in your database.
Last updated
