Klaviyo-sdk-beta NPM

Klaviyo JavaScript Beta SDK

Note: If you would like to request beta access to the new APIs, please fill out this brief form and you will be contacted by Klaviyo's product team once the beta release is available.

SDK version: 1.0.1
Revision: 2022-09-07.pre

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:

Catalogs
Client
Events
Flows
Lists
Metrics
Profiles
Segments
Templates

Installation

NPM

You can install this library using npm.

npm install klaviyo-sdk-beta

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 ConfigWrapper

import {ConfigWrapper} from 'klaviyo-sdk-beta'

ConfigWrapper("KLAVIYO PRIVATE KEY GOES HERE")

Or if ES6 isn't your thing

var KaviyoSdk = require('klaviyo-sdk-beta');

KaviyoSdk.ConfigWrapper("KLAVIYO PRIVATE KEY GOES HERE")

To edit the exponential backoff built into the ConfigWrapper you can pass optional parameters

import {ConfigWrapper} from 'klaviyo-sdk-beta'

ConfigWrapper("KLAVIYO PRIVATE KEY GOES HERE", {
    numOfAttempts: 5, // max number of rety attempts. Default is 3
    timeMultiple: 10, // how exponental the timing is. Default is 5
    startingDelay: 1000, // How long before first retry. Default is 500
})

NOTE:

The SDK retries on resolvable errors, namely: rate limits (common) and server errors on klaviyo (rare).

To call the `getProfile` operation:

import {Profiles} from 'klaviyo-sdk-beta';

const profileId = "PROFILE_ID";
const opts = {};

Profiles.getProfile(profileId, 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 {Profiles} from 'klaviyo-sdk-beta';

const profileId = "PROFILE_ID";
const opts = {};

// Just make sure you are calling with the async tag ie. async () => {}
try {
    response = await Profiles.getProfile(profileId, opts)
    console.log(response);
} catch (e) {
    console.log(error);
}

once again if you're not using ES6

var KaviyoSdk = require('klaviyo-sdk-beta');

var profileId = "PROFILE_ID";
var opts = {};

KaviyoSdk.Profiles.getProfile(profileId, opts)
    .then(data => 'Do Something Here')
    .catch(error => 'An error was thrown check the HTTP code with error.status');

if you need to use multiple api keys, you can forgo the wrapped api classes and make you own

import {ConfigWrapper, CatalogsApi} from 'klaviyo-sdk-beta'

const catalogApi = new CatalogsApi(ConfigWrapper("KLAVIYO PRIVATE KEY GOES HERE"))
const r = await catalogApi.createCatalogCategory(body)

Optional Parameters

Different endpoint include specific optional parameters. Here is a few examples how to use these and what they look like

Cursor based Pagination

Obtain the cursor value from the call you want to get the next page for, then pass it under the pageCursor optional parameter

const nextPageCursor = 'WzE2NDA5OTUyMDAsICIzYzRjeXdGTndadyIsIHRydWVd'

await Events.getEvents({pageCursor: nextPageCursor})

Filtering

Filter by passing the filter as a string as under the optional parameter filter

Read more about formatting your filter strings in our developer documentation

const filter = 'any(email,["henry.chan@klaviyo-demo.com","amanda.das@klaviyo-demo.com"])'

const response1 = await Profiles.getProfiles({filter}); // the same as {filter: filter}

Sparse Fields

The SDK expands the optional sparse fields into their own option, where you can pass a list of the desired items to include

const fieldsProfile = ["email"]
const fieldsList = ["name"]

await Profiles.getProfile(PROFILE_ID, {
    fieldsProfile,
    fieldsList
});

Includes

Includes you can pass a similar way, just add the values you want to include as a list

const include = ["lists","segments"]

await Profiles.getProfile(PROFILE_ID, {
    include,
});

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.

CatalogsApi

Create Catalog Category

const Catalogs.createCatalogCategory(body)

Create Catalog Category Relationships

const Catalogs.createCatalogCategoryRelationships(body, id, relatedResource)

Create Catalog Item

const Catalogs.createCatalogItem(body)

Create Catalog Item Relationships

const Catalogs.createCatalogItemRelationships(body, id, relatedResource)

Create Catalog Variant

const Catalogs.createCatalogVariant(body)

Delete Catalog Category

const Catalogs.deleteCatalogCategory(id)

Delete Catalog Category Relationships

const Catalogs.deleteCatalogCategoryRelationships(body, id, relatedResource)

Delete Catalog Item

const Catalogs.deleteCatalogItem(id)

Delete Catalog Item Relationships

const Catalogs.deleteCatalogItemRelationships(body, id, relatedResource)

Delete Catalog Variant

const Catalogs.deleteCatalogVariant(id)

Get Catalog Categories

const Catalogs.getCatalogCategories(opts)

Get Catalog Category

const Catalogs.getCatalogCategory(id, opts)

Get Catalog Category Items

const Catalogs.getCatalogCategoryItems(categoryId, opts)

Get Catalog Category Relationships

const Catalogs.getCatalogCategoryRelationships(id, relatedResource, opts)

Get Catalog Item

const Catalogs.getCatalogItem(id, opts)

Get Catalog Item Categories

const Catalogs.getCatalogItemCategories(itemId, opts)

Get Catalog Item Relationships

const Catalogs.getCatalogItemRelationships(id, relatedResource, opts)

Get Catalog Item Variants

const Catalogs.getCatalogItemVariants(itemId, opts)

Get Catalog Items

const Catalogs.getCatalogItems(opts)

Get Catalog Variant

const Catalogs.getCatalogVariant(id, opts)

Get Catalog Variants

const Catalogs.getCatalogVariants(opts)

Get Create Categories Job

const Catalogs.getCreateCategoriesJob(jobId, opts)

Get Create Categories Jobs

const Catalogs.getCreateCategoriesJobs(opts)

Get Create Items Job

const Catalogs.getCreateItemsJob(jobId, opts)

Get Create Items Jobs

const Catalogs.getCreateItemsJobs(opts)

Get Create Variants Job

const Catalogs.getCreateVariantsJob(jobId, opts)

Get Create Variants Jobs

const Catalogs.getCreateVariantsJobs(opts)

Get Delete Categories Job

const Catalogs.getDeleteCategoriesJob(jobId, opts)

Get Delete Categories Jobs

const Catalogs.getDeleteCategoriesJobs(opts)

Get Delete Items Job

const Catalogs.getDeleteItemsJob(jobId, opts)

Get Delete Items Jobs

const Catalogs.getDeleteItemsJobs(opts)

Get Delete Variants Job

const Catalogs.getDeleteVariantsJob(jobId, opts)

Get Delete Variants Jobs

const Catalogs.getDeleteVariantsJobs(opts)

Get Update Categories Job

const Catalogs.getUpdateCategoriesJob(jobId, opts)

Get Update Categories Jobs

const Catalogs.getUpdateCategoriesJobs(opts)

Get Update Items Job

const Catalogs.getUpdateItemsJob(jobId, opts)

Get Update Items Jobs

const Catalogs.getUpdateItemsJobs(opts)

Get Update Variants Job

const Catalogs.getUpdateVariantsJob(jobId, opts)

Get Update Variants Jobs

const Catalogs.getUpdateVariantsJobs(opts)

Spawn Create Categories Job

const Catalogs.spawnCreateCategoriesJob(body)

Spawn Create Items Job

const Catalogs.spawnCreateItemsJob(body)

Spawn Create Variants Job

const Catalogs.spawnCreateVariantsJob(body)

Spawn Delete Categories Job

const Catalogs.spawnDeleteCategoriesJob(body)

Spawn Delete Items Job

const Catalogs.spawnDeleteItemsJob(body)

Spawn Delete Variants Job

const Catalogs.spawnDeleteVariantsJob(body)

Spawn Update Categories Job

const Catalogs.spawnUpdateCategoriesJob(body)

Spawn Update Items Job

const Catalogs.spawnUpdateItemsJob(body)

Spawn Update Variants Job

const Catalogs.spawnUpdateVariantsJob(body)

Update Catalog Category

const Catalogs.updateCatalogCategory(body, id)

Update Catalog Category Relationships

const Catalogs.updateCatalogCategoryRelationships(body, id, relatedResource)

Update Catalog Item

const Catalogs.updateCatalogItem(body, id)

Update Catalog Item Relationships

const Catalogs.updateCatalogItemRelationships(body, id, relatedResource)

Update Catalog Variant

const Catalogs.updateCatalogVariant(body, id)

ClientApi

Create Client Event

const Client.createClientEvent(body, companyId)

Create Client Profile

const Client.createClientProfile(body, companyId)

Create Client Subscription

const Client.createClientSubscription(body, companyId)

EventsApi

Create Event

const Events.createEvent(body)

Get Event

const Events.getEvent(id, opts)

Get Event Metrics

const Events.getEventMetrics(id, opts)

Get Event Profiles

const Events.getEventProfiles(id, opts)

Get Event Relationships

const Events.getEventRelationships(id, relatedResource)

Get Events

const Events.getEvents(opts)

FlowsApi

Get Flow

const Flows.getFlow(id, opts)

Get Flow Action

const Flows.getFlowAction(id, opts)

Get Flow Action Flow

const Flows.getFlowActionFlow(actionId, opts)

Get Flow Action Messages

const Flows.getFlowActionMessages(actionId, opts)

Get Flow Action Relationships

const Flows.getFlowActionRelationships(id, relatedResource, opts)

Get Flow Flow Actions

const Flows.getFlowFlowActions(flowId, opts)

Get Flow Message

const Flows.getFlowMessage(id, opts)

Get Flow Message Action

const Flows.getFlowMessageAction(messageId, opts)

Get Flow Message Relationships

const Flows.getFlowMessageRelationships(id, relatedResource)

Get Flow Relationships

const Flows.getFlowRelationships(id, relatedResource, opts)

Get Flows

const Flows.getFlows(opts)

Update Flow

const Flows.updateFlow(body, id)

ListsApi

Create List

const Lists.createList(body)

Add Profile to List

const Lists.createListRelationships(body, id, relatedResource)

Delete List

const Lists.deleteList(id)

Remove Profile from List

const Lists.deleteListRelationships(body, id, relatedResource)

Get List

const Lists.getList(id, opts)

Get List Profiles

const Lists.getListProfiles(listId, opts)

Get List Profile Relationships

const Lists.getListRelationships(id, relatedResource, opts)

Get Lists

const Lists.getLists(opts)

Update List

const Lists.updateList(body, id)

MetricsApi

Get Metric

const Metrics.getMetric(id, opts)

Get Metric Aggregate

const Metrics.getMetricAggregate(body)

Get Metrics

const Metrics.getMetrics(opts)

ProfilesApi

Create Profile

const Profiles.createProfile(body)

Get Profile

const Profiles.getProfile(id, opts)

Get Profile Lists

const Profiles.getProfileLists(profileId, opts)

Get Profile Relationships

const Profiles.getProfileRelationships(id, relatedResource)

Get Profile Segments

const Profiles.getProfileSegments(profileId, opts)

Get Profiles

const Profiles.getProfiles(opts)

Subscribe Profiles

const Profiles.subscribeProfiles(body)

Suppress Profiles

const Profiles.suppressProfiles(body)

Unsubscribe Profiles

const Profiles.unsubscribeProfiles(body)

Unsuppress Profiles

const Profiles.unsuppressProfiles(body)

Update Profile

const Profiles.updateProfile(body, id)

SegmentsApi

Get Segment

const Segments.getSegment(id, opts)

Get Segment Profiles

const Segments.getSegmentProfiles(segmentId, opts)

Get Segment Relationships

const Segments.getSegmentRelationships(id, relatedResource, opts)

Get Segments

const Segments.getSegments(opts)

Update Segment

const Segments.updateSegment(body, id)

TemplatesApi

Create Template

const Templates.createTemplate(body)

Create Template Clone

const Templates.createTemplateClone(body, id)

Create Template Render

const Templates.createTemplateRender(body, id)

Delete Template

const Templates.deleteTemplate(id)

Get Template

const Templates.getTemplate(id, opts)

Get Templates

const Templates.getTemplates(opts)

Update Template

const Templates.updateTemplate(body, id)

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 becomes getCampaigns
Track & Identify becomes TrackIdentify

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 ConfigWrapper instantiation; public key is still required where its used.

@babel/cli superagent exponential-backoff

@infinitebrahmanuniverse/nolb-kl @zalastax/nolb-kl

1.0.1

2 years ago

1.0.0