Sendlane Custom Integration Setup & API v2

Sendlane’s Custom Integration JavaScript Tracking API and Server-Side API allow you to integrate your eCommerce platform with Sendlane. Sendlane’s APIs can support a completely custom eCommerce store or work in tandem with our existing eCommerce platform integrations!

Using a combination of Sendlane’s JavaScript and Server-Side APIs will bring your eCommerce store’s key metrics, like customer behavior and transaction history, into Sendlane where you can use your customer data to segment and target your audience.

Use Sendlane’s JavaScript API for data on your customers’ website activity:

Active on Site Contact visits your website
Product Viewed* Contact views a product on your website
Added to Cart* Contact adds a product to their cart
Checkout Started* Contact lands on the begin checkout page of your website
Custom Event

*Events can also be called using Sendlane’s Server-Side API

Use Sendlane’s Server-Side API for transactional data:

Placed Order Contact successfully completes an order and lands on the checkout complete page
Ordered Product An event for each product in a completed order
Fulfilled Order An order is marked as shipped to the Contact
Cancelled Order Contact cancels their order
Refunded Order Contact’s order is refunded

Configure Custom Integration in Sendlane

Set up the Sendlane Custom Integration within your Sendlane account if you are using a custom solution for your eCommerce store.

Generate API Keys

We recommend generating separate API keys for each integration and naming each token descriptively. To generate an API Key:

Click the Settings icon
Click API
Click + API Token
Enter a Token name
Click Create
Click Copy API Token

🚨 You must copy the API Key at this stage.

Once you exit the Access Token Created window you will not be able to access this API Key again.

Install Sendlane's Custom Integration Module

To install Sendlane's Custom Integration Module:

Click on the Integrations page
Click the Sendlane Custom Integration
Click Setup Integration
Enter your Store Name
Enter your Store URL
Select a default List
Select a customer address to assign
Click Continue

Setup for JavaScript Tracking API

Active on Site

To associate customers’ data with their Contact Profiles using Sendlane’s JavaScript Tracking API, customers first need to be identified via cookies.

Paste the snippet below in the header of your website, and replace INTEGRATION_TOKEN with your account’s Sendlane Custom Integration token. This will allow the script to track customer behavior on every page of your website.

<script src="https://sendlane.com/scripts/pusher.js" async data-token="INTEGRATION_TOKEN"></script>

You can access this snippet with your integration token populated by clicking Manage next to your Sendlane Integration > Copy code

Once this snippet is live on your website, any Active On Site activity will trigger for visitors who:

Sign up to receive your content via a Sendlane Pop-Up, OR
Click on a link in your email and land on your website

JavaScript Tracking API On Site Behaviors

🚨 Contacts must have been identified via the methods described above in Active On Site

This guide uses JSON snippets populated with example data, such as “123456789” for “product_id.” In order for On Site Behavior calls to pull accurate data, you will need to populate each snippet with the correct information for each of your eCommerce store’s properties.

Do not change Event IDs, or results will not be received correctly.

Product Viewed

Use the Product Viewed snippet to collect product browsing data. Product browsing data can be used to set up Automations or Segments for re-targeting Contacts who have shown interest in certain products.

Call the Product Viewed event (for example, on your website’s product page template) with a snippet like the following:

 <script>
    _Sendlane.push({
    "event": "product_viewed",
    "product_id": 12345,
    "email": "jimmy@sendlane.com",
});
</script>

Added to Cart

Use the Added to Cart snippet to track information on products your Contacts have added to their carts before they’ve landed on the begin checkout page. This allows you to send re-targeting emails before Contacts begin checkout.

Call the Added to Cart event with a snippet like the following:

<script>
    _Sendlane.push({
    "event": "added_to_cart",
    "email": "jimmy@sendlane.com",
    "line_items": [
        {
            "product_id": 12345,
        }
    ],
});
</script>

Checkout Started

Data from the Checkout Started snippet can be used to re-target Contacts who begin checkout but do not place an order within a specified period of time. Because this data will be used in abandoned cart emails, it is important to include all product details including name, pictures, links, and other pertinent information.

Call the Checkout Started event (for example, on your website’s “begin checkout” page) with a snippet like the following:

<script>
    _Sendlane.push({
    "event": "checkout_started",
    "email": "jimmy@sendlane.com",
    "checkout_id": 9876,
    "status": "pending",
    "checkout_url": "https://www.sendlane.com/checkout/9876",
    "subtotal": 19.99,
    "total_tax": 0,
    "total": 19.99,
    "total_items": 1,
    "currency": "USD",
    "line_items": [
        {
            "product_id": 12345678,
            "sku": "ABC123",
            "product_name": "tshirt #1",
            "quantity": 1,
            "item_price": 19.99,
            "total": 19.99,
        },
        {
            "product_id": 12345679,
            "sku": "ABC124",
            "product_name": "tshirt #2",
            "quantity": 1,
            "item_price": 19.99,
            "total": 19.99,
        }
    ]
});
</script>

Server-Side API Events

Sendlane’s Server-Side API should be used for data about orders placed on your website.

Getting Started

To use the following event calls, you’ll need your Sendlane Public API key and your Custom Integration Token.

Special Notes

Event IDs

In the snippets below, event_id should be a unique identifier for the order, such as order_id. If the same combination of event and id are sent more than once, Sendlane will record the first event and skip all subsequent events with the same event and id combination.

Total Property

The total property allows Sendlane to track revenue as the total monetary value of the event with which it is associated. The total for an order placed will equal the total amount spent on a single order. Changes made to the total after calculation will not be passed over to Sendlane.

Line Items

The line_items array should contain one dictionary for each item.

Time Properties

time is a special property that should be a UNIX timestamp of the order date and time, while date_created is a date string. If you use date_created, Sendlane will convert to time. The time property is only needed for historical syncs.

Order & Other Product Events

To track data about orders placed, make a Track request to Sendlane’s Server-Side API. From the order_placed event, ordered product events (such as product_purchased) will execute based on the content of the line_items array. When an order’s status changes to fulfilled, refunded, or canceled, other product events will be triggered.

Order Placed

Example snippet:

{
    "event": "order_placed",
    "token": "ABCDEFGHIJKLM1234567890",
    "order_id": 1001,
    "email": "jimmy@sendlane.com",
    "status": "processing",
    "subtotal": 19.99,
    "total_tax": 0,
    "total": 19.99,
    "total_items": 1,
    "currency": "USD",
    "discounts": {
        "discount_code": "25OFF",
        "discount_value": 4.99
    },
    "line_items": [
        {
            "product_id": 12345678,
            "sku": "ABC123",
            "product_name": "tshirt #1",
            "quantity": 1,
            "item_price": 19.99,
            "total": 19.99,
        },
        {
            "product_id": 12345679,
            "sku": "ABC124",
            "product_name": "tshirt #2",
            "quantity": 1,
            "item_price": 19.99,
            "total": 19.99,
        }
    ],
    "billing_address": {
        "first_name": "Jimmy",
        "last_name": "Kim",
        "email": "jimmy@sendlane.com",
        "company": "Sendlane",
        "address_1": "10620 Treena St",
        "address_2": "UNIT 250",
        "city": "San Diego",
        "state": "California",
        "state_code": "CA",
        "country": "United States",
        "country_code": "US",
        "postal_code": "92131",
        "phone": "8885552664"
    },
    "shipping_address": {
        "first_name": "Jimmy",
        "last_name": "Kim",
        "email": "jimmy@sendlane.com",
        "company": "Sendlane",
        "address_1": "10620 Treena St",
        "address_2": "UNIT 250",
        "city": "San Diego",
        "state": "California",
        "state_code": "CA",
        "country": "United States",
        "country_code": "US",
        "postal_code": "92131",
        "phone": "8885552664"
    },
    "customer_id": 123456789,
    "accepts_marketing": true,
}

Available Order Statuses

'cancelled'
'completed'
'failed'
'fulfilled'
'pending'
'processing'
'refunded'

Ordered Product

The ordered product event ( product_purchased) will execute based on the content of the line_items array in the order placed event.

Fulfilled Order

When an order’s status = fulfilled, the order_fulfilled event will trigger.

Cancelled Order

When an order’s status = cancelled, the order_cancelled event will trigger.

Refunded Order

When an order’s status = refunded, the order_refunded event will trigger.

Historical Data Sync

To sync historical customer and order data, you’ll need to complete customer_added, product_added, and order_placed requests that include "initial_sync": true and time or date_created set in the past.

🚨 You must sync product data nightly and for all changes

Use the product added call to set up a nightly sync of all product data, and sync product data when making changes.

Troubleshooting

I don't have backend access to my website, will I be able to use API v2’s event tracking calls?

No, backend website access is required for event tracking because snippets must be embedded to enable website tracking.

Contacts aren’t being sent through Automations even though I completed a historical data sync!

Data that is more than 24 hour old at the time of the sync will not trigger Automations even if an Automation’s conditions are met. If 90 days of data is synced and one Contact met the Automation’s condition less than 24 hours before the sync, they will be sent through the Automation.

Too much or not enough data is coming through!

Check the call for time values. time values should only be used when passing historical data into Sendlane. Calls without time values will default to the time the call was made.

A product’s price changed in the customer’s database!

Check your coupon code setup. If the customer has set up a coupon code to alter item_price instead of the subtotal, then the product price will be changed. Whenever Sendlane receives updated or new data about a product, the new data will overwrite the product’s existing data.

I can’t find Contacts’ customer IDs in Sendlane!

customer_id is generated by the eCommerce platform, not Sendlane.

Contacts’ LTV does not appear to be calculating correctly!

LTV is calculated as the amount from a customer_id’s cumulative order totals. Historical order data must be synced to see historical LTV data in Sendlane.

Some Contacts appear to be added to Sendlane and immediately unsubscribed!

If the Contact did not agree to accept marketing emails, the accepts_marketing value will be FALSE and trigger an immediate unsubscribe after data is passed to Sendlane.