Klaviyo JavaScript SDK
- SDK version: 1.0.1.1.0.1
Helpful Resources
Design & Approach
This SDK is a thin wrapper around our API. See our API Reference for full documentation on API behavior.
This SDK exactly mirrors the organization and naming convention of the above language-agnostic resources, with a few namespace changes to make it Pythonic (details in Appendix).
Organization
This SDK is organized into the following resources:
- Campaigns
- DataPrivacy
- ListsSegments
- Metrics
- Profiles
- Templates
- TrackIdentify
Installation
NPM
You can install this library using npm
.
npm install klaviyo-sdk
source code
Alternatively, you can also run this using this repo as source code, by running one of the following shell commands within the cloned repo:
npm install
and then running JavaScript from the cloned repo.
Usage Example
To instantiate the client
import {ApiClient} from 'klaviyo-sdk'
// Klaviyo sdk setup
const defaultClient = ApiClient.instance;
// Configure API key authorization: ApiKeyAuth
const ApiKeyAuth = defaultClient.authentications['ApiKeyAuth'];
ApiKeyAuth.apiKey = "KLAVIYO PRIVATE KEY GOES HERE";
Or if ES6 isn't your thing
var client = require('klaviyo-sdk');
// Klaviyo sdk setup
var defaultClient = client.ApiClient.instance;
// Configure API key authorization: ApiKeyAuth
var ApiKeyAuth = defaultClient.authentications['ApiKeyAuth'];
ApiKeyAuth.apiKey = "KLAVIYO PRIVATE KEY GOES HERE";
NOTE:
- The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).
metric-export
operation:
To call the import {Metrics} from 'klaviyo-sdk';
const metricId = "METRIC_ID";
const opts = {count: 100};
Metrics.metricExport(metricId, opts)
.then(data => 'Do Something Here')
.catch(error => 'An error was thrown check the HTTP code with error.status');
or if you want to use async await
import {Metrics} from 'klaviyo-sdk';
const metricId = "METRIC_ID";
const opts = {count: 100};
// Just make sure you are calling with the async tag ie. async () => {}
try {
data = await Metrics.metricExport(metricId, opts);
console.log(data);
} catch (e) {
console.log(error);
}
once again if you're not using ES6
var client = require('klaviyo-sdk');
var metricId = "METRIC_ID";
var opts = {count: 100};
client.Metrics.metricExport(metricId, opts)
.then(data => 'Do Something Here')
.catch(error => 'An error was thrown check the HTTP code with error.status');
Comprehensive list of Operations & Parameters
NOTE:
- Organization: Resource groups and operation_ids are listed in alphabetical order, first by Resource name, then by OpenAPI Summary. Operation summaries are those listed in the right side bar of the API Reference.
- For example values / data types, as well as whether parameters are required/optional, please reference the corresponding API Reference link.
- Some keyword args are required for the API call to succeed, the API docs above are the source of truth regarding which keyword params are required.
CampaignsApi
Cancel a Campaign
Campaigns.cancelCampaign(campaignId)
Clone a Campaign
Campaigns.cloneCampaign(campaignId, opts)
Create New Campaign
Campaigns.createCampaign(opts)
Get Campaign Info
Campaigns.getCampaignInfo(campaignId)
Get Campaign Recipients
Campaigns.getCampaignRecipients(campaignId, opts)
Get Campaigns
Campaigns.getCampaigns(opts)
Schedule a Campaign
Campaigns.scheduleCampaign(campaignId, opts)
Send a Campaign Immediately
Campaigns.sendCampaign(campaignId)
Update Campaign
Campaigns.updateCampaign(campaignId, opts)
DataPrivacyApi
Request a Deletion
DataPrivacy.requestDeletion(opts)
ListsSegmentsApi
Add Members to a List
ListsSegments.addMembers(listId, opts)
Create List
ListsSegments.createList(opts)
Delete List
ListsSegments.deleteList(listId)
Exclude Profile From All Email
ListsSegments.excludeGlobally(opts)
Get Global Exclusions & Unsubscribes
ListsSegments.getGlobalExclusions(opts)
Get All Exclusions for a List
ListsSegments.getListExclusions(listId, opts)
Get List Info
ListsSegments.getListInfo(listId)
Check if Profiles Are in a List
ListsSegments.getListMembers(listId, opts)
Check if Profiles Are in a List and not Suppressed
ListsSegments.getListSubscriptions(listId, opts)
Get Lists
ListsSegments.getLists()
Get List and Segment Members
ListsSegments.getMembers(listOrSegmentId, opts)
Check if Profiles Are in a Segment
ListsSegments.getSegmentMembers(segmentId, opts)
Remove Profiles From List
ListsSegments.removeMembers(listId, opts)
Subscribe Profiles to List
ListsSegments.subscribe(listId, opts)
Unsubscribe Profiles From List
ListsSegments.unsubscribe(listId, opts)
Update List Name
ListsSegments.updateListName(listId, opts)
MetricsApi
Get Metrics Info
Metrics.getMetrics(opts)
Query Event Data
Metrics.metricExport(metricId, opts)
Get Events for a Specific Metric
Metrics.metricTimeline(metricId, opts)
Get Events for All Metrics
Metrics.metricsTimeline(opts)
ProfilesApi
Exchange ID for Profile ID
Profiles.exchange(opts)
Get Profile
Profiles.getProfile(personId)
Get Profile's Events for a Specific Metric
Profiles.profileMetricTimeline(personId, metricId, opts)
Get Profile's Events for all Metrics
Profiles.profileMetricsTimeline(personId, opts)
Update Profile
Profiles.updateProfile(personId, opts)
TemplatesApi
Clone Template
Templates.cloneTemplate(templateId, opts)
Create New Template
Templates.createTemplate(opts)
Delete Template
Templates.deleteTemplate(templateId)
Get All Templates
Templates.getTemplates()
Render Template
Templates.renderTemplate(templateId, opts)
Render and Send Template
Templates.sendTemplate(templateId, opts)
Update Template
Templates.updateTemplate(templateId, opts)
TrackIdentifyApi
Identify Profile
TrackIdentify.identifyGet(data)
Identify Profile
TrackIdentify.identifyPost(opts)
Track Profile Activity
TrackIdentify.trackGet(data)
Track Profile Activity
TrackIdentify.trackPost(opts)
Appendix
Limitations
- The
api_key
is set at the global level: this means that if you manage multiple stores, you will need to run the code for each store in a different environment
Refresher on catching exceptions:
try {
await YOUR_CALL
} catch e {
print(e.status, e.reason, e.body, e.headers)
}
Namespace
In the interest of making the SDK follow conventions, we made the following namespace changes relative to the language agnostic resources up top.
- dashes
-
are removed in favor of camelCase - all other non-alphanumeric symbols, including spaces, are removed.
For example:
-
get-campaigns
becomesgetCampaigns
-
Track & Identify
becomesTrackIdentify
Parameters & Arguments
The parameters follow the same naming conventions as the resource groups and operations.
We stick to the following convention for parameters/arguments
- All parameters are passed as function args.
- All optional params, as well as all Body and Form Data params (including required ones), are passed in a single object param.
- All query and path params that are tagged as
required
in the docs are passed as positional args. - There is no need to pass in your private
api_key
for any operations, as it is defined upon client instantiation; public key is still required where its used.