NAV

Overview

Build wishlists, back-in-stock alert forms, save for later lists, gift registries, plugins, and web apps. Leverage Swym's powerful list of APIs to customise and extend the experience of any of our apps.

This API Reference defines all publicly supported Javascript APIs as well as the our Premium REST API.

We support Shopify, BigCommerce, Magento, WooCommerce, and many others ecommerce platforms, etc.

Please reach out to us at support@swymcorp.com if you have any inquiries, suggestions, or setup-related problems, and we will respond as soon as possible.

Initialization

To avoid slowing down your website's critical loading path, Swym Javascript APIs are loaded asynchronously on your site.

The recommended technique to load scripts in modern web applications by browser standards is to load scripts asynchronously

However, this means that you need to wait for the Swym APIs to load before you can use the APIs.

We have a simple Javscript callback where you can add your custom code too, which will run after our apps are loaded on your storefront.

window.SwymCallbacks

The window.SwymCallbacks array is the entry point to the Swym Javascript SDK.

It is a callback queue that executes after the window.load event, it is a good place to add your custom code.

window.SwymCallbacks = [] | Array

//Executed after SWYM has loaded all necessary resources.
function onSwymLoadCallback(swat) {
  // Please make all SWYM-related API calls inside this function.
  // You can use the swat argument within this scope.
}
if (!window.SwymCallbacks) {
  window.SwymCallbacks = [];
}
window.SwymCallbacks.push(onSwymLoadCallback);
Arguments Type Comments
swat Object Swym Javascript SDK is passed as the first argument to the callback function.
onSwymLoadCallback function is a callback function that is called after Swym loads and swat is passed as the first argument. This function name can be an arbitrary name of your choice.

window._swat

if (window._swat) {
  console.log("Swym scripts tags are installed on your store");
}

swat is the Javascript wrapper that contains APIs, settings, and functionality for Swym Apps.

Its installed on your store via a script tag specific to your ecommerce plaform (e.g., Shopify or BigCommerce) during app installation.

swat | argument | window._swat | Object

You may also use window._swat to check if Swym script tags are installed on your store.

Testing APIs in the browser console

Example

window.onload = (event) => {
  console.log("page is fully loaded");
  // check if swym is installed.
  if (window._swat) {
    console.log("Swym scripts tags are installed on your store");
    // create a product object
    let product = {
      empi: "productID",
      epi: "variantID", // variant id
      du: "product url", // product url
    };
    // test the addToWishList APIs
    window._swat.addToWishList(product, console.log);
    // check the console for the response or errors.
  } else {
    console.log(
      "Swym scripts tags are not installed on your store, or maybe in waiting"
    );
  }
};

You can test any of our APIs in the browser console by using the window._swat object. Simply replace swat in places where it is used in the documentation with window._swat.

Parameter Type Description
window._swat Object Swym Javascript SDK on the global scope for browser console testing of our APIs.

In situations where you cannot use SwymCallbacks, you may substitute it with window._swat. You can trigger it after the window.onload event.

Single Wishlist

A simple Add To Wishlist Button.

The Single Wishlist APIs are designed to help you add a simple Wishlist button to your store.

A default wishlist is created for every user in your store, when they first add a product to their wishlist.

You can make a simple button like the one shown on the right and have it perform the Add to Wishlist or Remove from Wishlist actions on click event.

Ideally, the button should be placed on the product page or collection page. They can also be wired for the following scenarios:

Event Location
onclick button on a product page or PDP
onclick button on a product quick view modal
onclick buttons on a collections page with multiple products
onclick buttons on a widget of multiple products, Eg: related products, top wishlist products, etc.

Reference APIs: Add to Wishlist, Remove from Wishlist,
Fetch Default Wishlist.

Add to wishlist

Adds a product to the default wishlist.

swat.addToWishList(product, successCallBack, failureCallBack)

Example

// Define your "product" before adding it to the wishlist (product).
let product = {
  epi: 41254709264582, // unique variant ID of the product.
  empi: 7096252727494, // Product ID or master product ID
  du: "https://demo.swym.it/products/1-light-pendant", // canonical product url.
  cprops: { // optional custom properties for frontend use only.
    "customized": true,
    "wash_instructions": "tumble dry"
  }
}

// Add the "product" to the wishlist.
swat.addToWishList(product, function(response) {
  console.log("product successfully added to wishlist", response);
}, function(error) {
  console.log("there was an error adding the product to wishlist", error);
});

Response

{
  "event": {
    "empi": 7096252727494, // product id 
    "epi": 41254709264582, // variant id
    "du": "https://demo.swym.it/products/1-light-pendant", // canonical product url
    "cprops": { // optional custom properties
    "customized": true,
    "wash_instructions": "tumble dry"
    },
    "lid": "a03a8d25-48e8-4d7a-92e9-ac86ecccc267", // list id
    "pr": 150.0 // product price
    "di": "37ec0c4b-a930-4d13-87c1-ac08205402a1", // device id
    "bt": "Swym Marketing", // collections name
    "dt": "1 LIGHT PENDANT",  // product title
    "et": 4,  // event type (4 = add to wishlist)
    "cts": 1675666526408, // client timestamp
    "sku": "24", // sku

  },
  "message": "Successful"
}
Argument Description
product is a simple javascript object that contains product information like productId, variantId, and the canonical product url..
successCallBack is a callback function that is called when the product is successfully added to the wishlist.
failureCallBack is a callback function that is called when there is an error while adding the product to the wishlist.

The product is a simple product that contains the following fields.

Argument Type Description
epi int/string The variant ID must be unique to a product.
empi int/string product id or product master id (if there is a group product id with different variant ids)
du string Canonical product url
cpropsoptional object object used as custom properties for frontend use only.

Remove from wishlist

Removes a product from the default wishlist

swat.removeFromWishList(product, callbackFn)

Example


// Define your "product" before removing it from the wishlist.
let product = {
 epi : 41255230701766, // variant id 
 empi : 7096437407942,  // Master product id / Product Id 
 du :  "https://demo.swym.it/products/ 12-inches-round-rose-gold-frame-wall-mirror " // cannonical product url
}

// Remove the "product" from the wishlist.
swat.removeFromWishList(product, function(response) {
    console.log("product successfully removed from wishlist", response);
}, function(error) {
    console.log("there was an error while removing the product from wishlist", error, product);
});

Response

{
  du: "https://demo.swym.it/products/1-light-pendant", // canonical product url
  empi: 7096252727494, // product id
  epi: 41254709264582, // variant id
  et: 4, // event type 
  type: "product-variant", // product level or variant level
}
Definition Comments
product is a simple javascript object that contains product information like "product id," "variant id," "canonical product url," and optional "custom properties" provided by the API caller.
successCallBack is a callback function that is called when the product is successfully removed.
failureCallBack is a callback function that is called when there is an error while removing.

The product is a simple javascript object that contains the following fields.

Argument Type Description
epi int/string The variant ID must be unique to a product.
empi int/string The product master id / Product Id (if there is a group product id with different variant ids)
du string Canonical product url that is used to identify the product.

Fetch Default Wishlist

Example


// Fetch the users wishlist and print it to the console.
swat.fetch(function(allWishlistedProducts) {
  // Prints the current users wishlist - 
  console.log("successfully retrieved the wishlist", allWishlistedProducts);
}, function(error) {
  console.log("There was an error while fetching the wishlist", error)
});

Response

[
  {
    "epi": 41254709264582, // Variant ID
    "empi": 7096252727494, // Product Master id
    "dt": "1 LIGHT PENDANT", //Product Handle  or Product Title 
    "pr": 150 // Product price or Variant Price 
    "sku": "24", // SKU of the product
    "bt": "Swym Marketing", // Brand name in the product.
    "du": "https://demo.swym.it/products/1-light-pendant?variant=41254709264582", // product url with variant query param
    "iu": "https://cdn.shopify.com/s/files/1/0534/3635/0662/products/1LIGHTPENDANT_620x620.jpg?v=1637584280",// Image Url
    "cprops": { // your custom properties - use this to render it on the frontend.
      "customized": true,
      "wash_instructions": "tumble dry"
    },
    "lid": "0bafa053-9373-4cd4-8030-373a4606cd69", // Default List ID of the wishlist
    "uts": 1675148899186, // Updated timestamp
    "cts": 1675148899186, // Added to Wishlist timestamp
  }
]

The swat.fetch API returns an array of product added to the default wishlist.

Note Even if the API is called multiple times, this API caches the response for performance and does not make network calls unless required.

swat.fetch(callbackFn) | Returns array of products or eventObjects

Definition Comments
callbackFn is a callback function that is called when the wishlist is successfully fetched.

Multiple Lists - (Javascript)

The Swym Javascript SDK supports having multiple (wish)lists for a user,
e.g., my loungemy bedroom, etc.; or, in the case of fashion, my outdoor lookmy summer list, etc.

Each list can have multiple items or products, and the lists can be shared with other users.

Table of Contents :

All of the Multiple List APIs are listed in the table below for quick reference.

API Name Use case
- Create Lists create a new List for a shopper using the list name.
- Fetch all Lists Get all the lists that have been created for a email / session.
- Update List attributes updates the list attributes(lname, lnote)
- Delete a List deletes a list along with all of its contents and items.
- Get list details fetches the information about a list.
- Fetch list Contents fetches the list contents (items) for a shopper
- Add item to a list adds item to a list
- Update an list item updates the list items for a shopper // eg: used in change variant scenario.
- Delete an Item from a list removes the list item which is passed from a list.
- Add multiple products to a list adds multiple products to a list
- Delete multiple products from a list deletes multiple products from a list

Create a new list

Request

// define the list config
let newListConfig = {
  "lname": "bucket list for summer", // list name is required
};

// Define success and error callback functions
let sucessCallBackFn = function(listObj) { 
  // executed when successfully created a new list
  console.log("New list created", listObj);
}
let errorCallBackFn = function(xhrObject) {
  // something went wrong.
  console.log("Error creating list", xhrObject);
}


// create a new list with the above config
swat.createList(newListConfig, sucessCallBackFn, errorCallBackFn);

Response

{
    "di": "37ec0c4b-a930-4d13-87c1-ac08205402a1", // device id
    "userinfo": null, // user info if logged in
    "lty": "wl", // list type
    "lprops": { // optional list properties.
        "dry instructions": "tumble dry"
    },
    "cts": 1675665972622, // created timestamp
    "lname": "bucket list for summer", // list name
    "lid": "59179e9f-139d-4857-bcdd-3ad88a38b47d", // list id
    "pid": "KABSbuGyYCuM6/IV7e7cGxT1978LieU1jRdMt6XhYfo=", // merchant id
    "uts": 1675665972622, // updated timestamp
    "lhash": "YnVja2V0LWxpc3QtZm9yLXN1bW1lcg==" // list hash unique to list name
}

Creates a list with a name and attributes configured via the List Config and returns the newly created list object.

swat.createList(newListConfig, successCallback, errorCallback)

Argument Type Description
newListConfig object List Config is a simple object containing config required for creating new list eg name, properties, etc.
successCallback function a callback that will be called if there is a success response.
errorCallback function a callback that will be called if there is a Error response.

Fetch all lists

Get all lists for the current session or for an authenticated shopper.

swat.fetchLists(opts) | Array of Lists

Example

// Define success and error callback functions
let successCallBackFn = function(lists) {
  // successfully fetched my lists 
  console.log("Fetched all my current lists", lists);
}
let errorCallBackFn = function(xhrObj) {
  // something went wrong 
}

// call fetchLists
swat.fetchLists({
  callbackFn: successCallBackFn,
  errorFn: errorCallBackFn
});

Example response - Array of Lists

[{
  "uid": "example-uid",
  "cts": 1585080432834,
  "lname": "list_id 15",
  "cby": "example@example.org",
  "lid": "31b8fa07-example-ex-ex-ex",
  "pid": "example-providerid",
  "st": 1,
  "uts": 1585080432834,
  "uby": "example@example.org",
  "cfor": "example@example.org"
}]
Argument Type Description
opts.callbackFn function Success callback function which will be called with the response
opts.errorFn function Error callback function which will be called on unsuccessful response

Update list attributes

Updates all the attributes of a list such as a note, name, and custom properties for a given list id( lid.) and returns the updated list object.

swat.updateList(listUpdateMap, successCallback, errorCallback)

var listUpdateMap = {
  "lid": "list id to update, mandatory",
  "lname": "List name, mandatory",
  "lnote": "Updated List note, optional"
};
// Update lprops - custom properties for frontend use only - optional
// listUpdateMap.lprops = {customVal1: "custom value"};

swat.updateList(listUpdateMap, function(updateListObj) {
  // successfully updated list
  console.log("Updated list", updateListObj.lid);
}, function(xhrObject) {
  // something went wrong
});

Update list

Argument Type Description
listUpdateMap object List Update Input. Object containing params required for the list update
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Delete List

Deletes a list for a given list id( lid.) and returns the deleted list object.

swat.deleteList(listId, successCallback, errorCallback)

Example

swat.deleteList(listId, function(deletedListObj){
  // successfully deleted list
  console.log("Deleted list with listid", deletedListObj.lid);
}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listId guid List id to delete
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Get the lists details.

This API returns the list information for a given lid (list id); the details include the list and the list items.

swat.fetchListDetails(params, successCallback, errorCallback)

swat.fetchListDetails({lid: listId}, function(listContents){
  // successfully fetched list details
  console.log("Fetched list details", listContents);
}, function(xhrObj) {
  // something went wrong
});

Example Response - Map containing List and an array of List Items

{
  "list": {
    "uid": "example-uid",
    "cts": 1585080432834,
    "lname": "list_id 15",
    "cby": "example@example.org",
    "lid": "31b8fa07-example-ex-ex-ex",
    "pid": "example-providerid",
    "st": 1,
    "uts": 1585080432834,
    "uby": "example@example.org",
    "cfor": "example@example.org",
    "cnt": 1
  },
  "items": [
    {
      "epi": 111,
      "empi": 123,
      "cprops": {},
      "note": null,
      "qty": 2,
      "lid": "31b8fa07-ex-ex----",
      "cby": "example@example.org",
      "cts": 1585080751632
    }
  ]
}

Used most commonly to fetch list information along with list items for a given list id.

Argument Type Description
lid guid list-id the unique id to fetch contents.
successCallback function Success callback function which will be called with the response.
errorCallback function Error callback function which will be called on unsuccessful response.

Fetch List Contents

This API returns the an array of list contents (products) for individual list for a given lid (list id). This api is similar to fetchListDetails but returns only the list items.

swat.fetchListCtx(params, successCallback, errorCallback)

swat.fetchListCtx({lid: lid}, function(listContents){
  // successfully fetched list contents
  console.log("Fetched list contents", listContents); 
}, function(xhrObj) {
  // something went wrong
});

Example Response - Array of List Items

[
  {
    "epi": 1111111, //variant id
    "empi": 123, //product id
    "cprops": {}, //custom properties
    "note": null, //note
    "qty": 2, //quantity
    "lid": "31b8fa07-ex-ex----", //list id
    "cby": "example@example.org",   //created by
    "cts": 1585080751632 //created timestamp
  }
]

Used to fetch the list items belonging a given list id.

Argument Type Description
params.listId guid List id to fetch contents
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Add Item to a list

Adds an item to the list. You can call this function inside the onSwymLoadCallBack method using the swat argument object.

var listItem = {
  epi: epi, // Unique variant ID of the item
  empi: empi, // Master Product Id
  du: du, // Product URL
  qty: qty, // quantity 
  note: note, //optional
  cprops: {} // Optional custom attributes
};


swat.addToList(listId, listItem, function(newListItem){
  // successfully added list item
  console.log(`Added item to list list Id ${listId}`, newListItem);
}, function(xhrObj) {
  // something went wrong
});

swat.addToList(listId, product, successCallback, errorCallback)

Argument Type Description
listId guid List id to add to the list.
listItem object List Item Input. Object containing params required for the list entry
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Update an list item

Updates the list item with the given listItemId with the given product object you may also update cprops, note. You can call this function inside the onSwymLoadCallBack method using the swat argument object.

swat.updateWishlistEvent(listId,eventsToUpdate, callbackFn, errorFn)

  var product = {
    epi: epi,  // variant id of the product to be updated
    empi: empi, // product id of the product to be updated
    du: du, // canonical uri of the product to be updated
    qty: qty, // quantity
    note: note, //optional note
    cprops: {} // Optional custom attributes
  };

  swat.updateListItem(listId, product, function(updatedListItem){
    // successfully updated list item
    console.log("Updated the list item", updatedListItem)
  }, function(xhrObj) {
    // something went wrong
    console.log("There was an error while updating",xhrObj)
  });
Argument Type Description
listId guid List id to add to
product object Object containing params required for the list entry
product.epi int/string Variant id of the product to be added
product.empi int/string Product id of the product to be added
product.du string Canonical uri of the product to be added
product.qty optional int Defaults to 1. Quantity included for the add action
product.note optional string Optional note
product.cprops optional object Optional. Map of custom fields
product.lbls optional array [string] Optional. Array of strings indicating labels, rooms, etc. for HTC. Only one value supported in array. eg: ["Room1"]
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Delete an Item from a list

Deletes an item from the list. You can call this function inside the onSwymLoadCallBack method using the swat argument object.

swat.deleteFromList(listId, product, successCallback, errorCallback)

This is required to delete the item from the list

var listItem = { // item to be deleted
  epi: epi,  // unique variant id  per listid
  empi: empi, // product id 
  du: du // product url. 
};

swat.deleteFromList(listId, listItem, function(deletedListItem){
  // successfully deleted list item
  callback(deletedListItem);
}, function(xhrObj) {
  // something went wrong
});
Argument Type Description
listId guid List id to delete from
listItem object List Item Input. Object containing params required for the list entry
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Add multiple products to a list

Add multiple list items (products) to a list. You can call this function inside the onSwymLoadCallBack method using the swat argument object. This API is useful when you want to add multiple products to a list at once.

swat.addProductsToList(listId, arrayOfProducts, successCallback, errorCallback)

swat.addProductsToList(listId, arrayOfProducts, function(resp){
  // successfully added multiple list items
  // resp will contain the list items added to the list
   console.log(resp);

}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listId guid List id to add to
arrayOfProducts array Array of List Item Input. Object containing params required for the list entry. Max 10 at a time, affects response times
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Remove multiple products from a list

Remove multiple list items in a single call.

The removed items are returned in the successCallback function. This API is useful when you want to add a product to multiple lists at once.

Note: epi (variant id), empi (product id), and du (product url) are required to remove the item from the list.

swat.removeProductsFromList(listId, arrayOfProducts, successCallback, errorCallback)

This API takes an listId and an array of List Item Input object. and removes all the listItems from the list.


var product = [{ // item object to be deleted
  epi: epi,  // unique variant of the product per listid
  empi: empi, // product id 
  du: du // product url. 
}]

swat.removeProductsFromList(listId, product, function(resp){
  // successfully removed multiple list items from a single list  (many items : 1 list)
  // resp will contain the list items removed from the list
   console.log(resp);

}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listId guid List id to remove from
product array Array of List Item Input. Objects containing item parameters required for the list successCallback
errorCallback function Error callback function which will be called on unsuccessful response

Add product to multiple lists

Add an item or product to multiple lists in a single network request.

The added items are returned in the successCallback function. This API is useful when you want to add a product to multiple lists at once.

Example: Add an item (product) to 2 lists.

// list item object to be added to lists.
var product = { // item 
  epi: epi,  // unique variant of the product per listid
  empi: empi, // product id 
  du: du // product url. 
}

let arrayOfListId = [`listId1`, `listId2`]; // guids of the lists to add to max 10 at a time.

swat.addProductToLists(product, arrayOfListId, function(resp){
  // successfully added an item to multiple lists (1 item to : many lists)
  // resp will contain the list items added to the lists
   console.log(resp);

}, function(xhrObject) {
  // something went wrong
});

swat.addProductToLists(product, arrayOfListId, successCallback, errorCallback)

This API accepts an array of arrayOfListId and a List Item Input object, then adds the item to all of the lists in the array.

Argument Type Description
product object List Item Input. Object containing params required for the list entry
listIdArray array Array of List ids to add to. Max 10 at a time, affects response times
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Remove a product from multiple lists

Remove a product from multiple lists in a single API call.

Example: Remove an product from 2 lists

// product you want to delete.
var product = { // 
  epi: variantId,  // unique variant id of the product per listid
  empi: productMasterId, // product master id.
  du: productURL // product url. 
}

let listIdArray = ["list id 1", "list id 2"]; // GUID of the lists to remove from max 10 at a time

swat.removeProductFromLists(product, listIdArray, function(removedProduct){
   // successfully removed list item from the all of the arrayOfListId
   console.log("Success! removed the product from provided lists",removedProduct);

}, function(xhrObject) {
  // something went wrong
  console.log("Error",xhrObject);
});

swat.removeProductFromLists(product, listIdArray, successCallback, errorCallback)

This API takes an array of list id (lid) and a "single" product javaScript object and removes the product from all lists that have the respective lid or list id.

Argument Type Description
product object List Item Input. product that must be removed 
listIdArray array Array of list Id (lid) to remove from. Max 10 at a time.
successCallback function Success callback function which will be called with the response removedListItem
errorCallback function Error callback function which will be called on unsuccessful response

Social sharing of Wishlist

Share on social media

This API creates the unique URL for a particular sharing platform and opens a new dialog in that platform to perform the sharing step. For eg., for facebook, the share page will be opened in a new window.

swat.shareListSocial(listId, shareUrlTemplate, platform, note, errCallBack)

swat.shareListSocial(
  null,
  fromName,
  "https://www.facebook.com/sharer.php?u={{shareurl}}&t={{note}}",
  "facebook",
  "Hello World",
  function (data) {
    console.log(data);
  }
); // will open facebook share dialog
Argument Type Description
listid guid List id to share. Pass null if multiple lists is not enabled
fromName string Sharer's name for reporting
platformShareUrlTemplate string The social platform-specific share URL with Mustache tags. Out of the box, platforms supported are "facebook", "twitter". To get share urls for these, use the variable - swat.retailerSettings.Wishlist.SharingModes. This has the default icon url, share url and key for each of these platforms. Again, new platforms can be added here and/or default icons can be changed for you if you need it.
platform string The key to one of the sharing platforms. By default, one of "facebook", "twitter"
note string Some platforms allow to send a custom note along with shared url. This field is to capture that message. Amongst the defaults, at the moment, notes only work with twitter.
errCallBack function Function that gets called if there is an error. Called with error message as argument.

Returns a unique URL that can be shared anywhere. This URL will return the user who clicks on it back to the site into the default share wishlist page. This page can be overridden from the retailer settings if need be.

swat.generateSharedListURL(listId, callbackFn, errCallBack)

swat.generateSharedListURL(
  null,
  function (data, sharedListId) {
    console.log(data);
  }, // returns the generated url
  function (data) {
    console.log(data);
  }
);
Argument Type Description
listid guid List id to share. Pass null if multiple lists is not enabled
successFn function Function that gets called if the URL is generated successfully. The generated url and sharedListId are sent as arguments to this function.
errorFn function Function that gets called if the URL generation fails. Error message is passed as argument.

Email Wishlist

swat.sendListViaEmail(params, callbackFn, errorCallback)

Sends an email with the wishlist contents of the current user to a given email id.

swat.sendListViaEmail(
  {
    toEmailId: "abc@xyz.com",
    fromName: "ABC XYZ",
    note: "Hey, check out these products!",
    lid: listId, // null when multiple list is not enabled
    cprops: {}, // custom props for the share, future usage
  },
  function (r) {
    console.log("Email sent!");
  },
  function (r) {
    console.log("Email failed!");
  }
);
Argument Type Description
params.toEmailId string An email Id to send the wihlist to
params.fromName string The sender's name
params.note string Some personal note that needs to be sent along with the email contents
params.lidoptional guid If multiple wishlist is not enabled pass null
params.cpropsoptional object Reserved for future
callbackFn function A callback function which takes a single argument (JSON response from the swym service)
errorCallback function A callback function that gets called if the send failed

Report wishlist share

swat.reportListShare(listid, fromName, medium, note, shareurl)

A lower level API that tracks list shares, needs to be called on custom share user interfaces built for custom implementations

swat.reportListShare(listid, fromName, medium, note, shareurl);
Argument Type Description
listid guid List id to share. Pass null if multiple lists is not enabled
fromName string Sharer's name
medium string The social platform medium shared on - "facebook" or if it is copy "copylink"
note string The note that was added when shared
shareurl url The url that was shared

Connecting shopper account

Swym APIs allow a couple modes of connecting shopper account either via a native storefront login or a via a connect link.

Native storefront login

Native storefront login is detected asynchronously, and raises a Swym JSEvent swat.JSEvents.customerInfoRefreshed which can be subscribed

swat.evtLayer.addEventListener(swat.JSEvents.customerInfoRefreshed, function(evt) {
  swat.authCheck(function(shopperContext) {

  });
});

Example Response Shopper known

{
  "authn": true,
  "email": "shopper email",
  "regn": {
    "userinfo": { // where available
      "fname": "", // where available
      "lname": "", // where available
      "acc_mkt": null // accepts marketing flag - boolean where available
    }
  }
}

Example Response Shopper unknown

{
  "authn": false,
  "email": null
}

Save shopper context -- saveShopperContext

Save shopper context via Swym shopper capture interfaces

var params = {
  fname: "first name",
  lname: "last name",
  src: "", // enum(remoteauth, wlreminder, bispaform)
  app: "", // enum(Wishlist, Watchlist)
  skipConnect: false
};
swat.saveShopperContext(email, params, successCallback, errorCallback)
Argument Type Description
email string A valid shopper email address
params.fname string Optional. Shopper first name
params.lname string Optional. Shopper last name
params.acceptMarketing boolean Optional. Set param to true or false if user has chosen to not check an Add to mailing list checkbox
params.src enum(remoteauth, wlreminder, bispaform) Optional.Enumerated list of sources for email capture report
params.app enum(Wishlist, Watchlist) Optional.Enumerated list of apps for email capture report
params.skipConnect boolean Optional. Set to true when merchant/retailer settings has a flag to avoid sending remote connect email
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called if unsuccessful response.

Disconnect shopper context -- disconnectShopperContext

Request Swym to "logout" shopper context associated with device either by storefront logout or intiate a swym disconnect

swat.disconnectShopperContext(successCallback, errorFn)
Argument Type Description
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called if unsuccessful response.

Save for Later List (SFL)

The Save for Later APIs are specially designed for holding items from the cart but are not limited to the cart page.

You can customise the Save for Later feature and how it interacts in your store using these APIs.

These APIs are housed inside swat.SaveForLater Object.

Initialize

Before using the Save for Later list, it must first be initialized; this function initialises.

You can use this function as a fetch or as a create mechanism when the user first interacts with the store; If the list exists, it returns the list items; if the list does not exist, this function will create a new list for the user and returns the
list id.

swat.SaveForLater.init(successCallBackfn, errorcallbackFn)

Example request

window._swat.SaveForLater.init(
  function successCallBackFn(response) {
    // The response includes the list ID (lid), which can be used to interact with the save for later list.
    console.log("Successfully Initialized Save for Later", response);
  },
  function errorCallbackFn(error) {
    console.log("There was an error", error);
  }
);

Example response

{
    "list": {
        "di": "37ec0c4b-a930-4d13-87c1-ac08205402a1",
        "lty": "sfl",
        "uid": null,
        "cts": 1676803655238,
        "lnote": null,
        "lname": "My SFL List",
        "cby": null,
        "lid": "b41f893a-e052-400e-8d68-e6b37791bf3d",
        "pid": "KABSbuGyYCuM6/IV7e7cGxT1978LieU1jRdMt6XhYfo=",
        "st": 1,
        "cprops": {},
        "id": "d732e670-0af6-496c-b2e6-700af6e96cfd",
        "uts": 1676803655238,
        "ldesc": {},
        "uby": null,
        "cfor": null
    },
    "items": [
        {
            "di": "37ec0c4b-a930-4d13-87c1-ac08205402a1",
            "bt": "Swym Marketing",
            "clbls": [],
            "uid": null,
            "dt": "1 LIGHT PENDANT",
            "cts": 1676803659589,
            "empi": 7096252727494,
            "cby": null,
            "lid": "b41f893a-e052-400e-8d68-e6b37791bf3d",
            "du": "https://demo.swym.it/products/1-light-pendant?variant=41254709264582",
            "pid": "KABSbuGyYCuM6/IV7e7cGxT1978LieU1jRdMt6XhYfo=",
            "epi": 41254709264582,
            "cprops": {},
            "id": "4130b4ec-1def-40b7-b0b4-ec1def20b734",
            "uts": 1676803659589,
            "iu": "https://cdn.shopify.com/s/files/1/0534/3635/0662/products/1LIGHTPENDANT_620x620.jpg?v=1637584280",
            "qty": 1,
            "uby": null,
            "pr": 150.0,
            "vi": null
        }
    ],
    "userinfo": null,
    "pagination": {
        "totalcount": 1,
        "next": null,
        "limit": null
    }
}
Argument Type Description
successCallBackFn function A callback function with a single argument, which is a JSON response on success.
errorCallBackFn function A callback function with a single argument, which is a JSON response on error.

Add products to SFL list

_swat.SaveForLater.add(options, successCb, errorCb)

Example request

window._swat.addToSFL(
  {
    SFLProductList: [
      {
        epi: 123,
        du: "https://yourstore.com/products/your-awesome-product",
        empi: 1234,
      },
    ],
    lid: "67c06a80-f103-403c-80f8-a450e964d9f6",
    //lid is the listid value returned as a response from _swat.initializeSFLList
  },
  function (response) {
    console.log("Added product(s) to SFL", response);
  },
  function (error) {
    console.log("Add to SFL error", error);
  }
);

Another example request with cprops

window._swat.addToSFL(
  {
    SFLProductList: [
      {
        epi: 123,
        du: "https://yourstore.com/products/your-awesome-product",
        empi: 1234,
        cprops: { personalised: true },
      },
    ],
    lid: "67c06a80-f103-403c-80f8-a450e964d9f6",
    //lid is the listid value returned as a response from _swat.initializeSFLList
  },
  function (response) {
    console.log("Added product(s) to SFL", response);
  },
  function (error) {
    console.log("Add to SFL error", error);
  }
);

Add single or multiple products to the Saved for Later list. You can call this method once the window._swat object is initialized. This API operates at the epi, i.e. product variant level as set by the store.

This API can be called in the below scenarios,

Tip - Before showing a button for 'Save for Later', it is best to first check if the product or variant is already in the list, by using the "fetch" API.

Argument Type Description
options.SFLProductList array Array of List Item Input. Object containing parameters required for the list entry.
options.lid guid List id to add to
(This value is returned from the _swat.initializeSFLList call.)
successCb function Success callback function which will be called with the response
errorCb function Error callback function which will be called on unsuccessful response

In the example, the request adds a single product variant to the saved for later list. Please note that the these parameters are mandatory ones (epi, empi and du).

Remove products from SFL list

_swat.removeFromSFL(options, successCb, errorCb)

Remove a single or multiple products from the Saved for Later list. You can call this method once the window._swat object is initialized. This API operates at the epi, i.e. product variant level as set by the store.

window._swat.removeFromSFL(
  {
    SFLProductList: [
      {
        epi: 123,
        du: "https://yourstore.com/products/your-awesome-product",
        empi: 1234,
      },
    ],
    lid: "67c06a80-f103-403c-80f8-a450e964d9f6",
    //lid is the listid value returned as a response from _swat.initializeSFLList
  },
  function (response) {
    console.log("Removed product(s) from SFL", response);
  },
  function (error) {
    console.log("Remove from SFL error", error);
  }
);
Argument Type Description
options.SFLProductList array Array of List Item Input. Object containing parameters required for the list entry.
options.lid guid List id to add to
(This value is returned from the _swat.initializeSFLList call.)
successCb function Success callback function which will be called with the response
errorCb function Error callback function which will be called on unsuccessful response

In the example, removeFromSFL removes a previously added product from the SFL list.

Update products in SFL list

_swat.updateSFL(options, successCb, errorCb)

Update attributes like cprops for a single or multiple products in the Saved for Later list. You can call this method once the window._swat object is initialized. This API operates at the epi, i.e. product variant level as set by the store.

Note that each product in the SFL list is uniquely identified by the epi, empi value pair. Hence, to update the properties for a particular product, make sure to send the correct epi, empi value pair in the API call.

Example request

window._swat.updateSFL(
  {
    SFLProductList: [
      {
        epi: 123,
        du: "https://yourstore.com/products/your-awesome-product",
        empi: 1234,
        cprops: { thisAttributeIsUpdated: true },
      },
    ],
    lid: "67c06a80-f103-403c-80f8-a450e964d9f6",
    //lid is the listid value returned as a response from _swat.initializeSFLList
  },
  function (response) {
    console.log("Updated product(s) in SFL", response);
  },
  function (error) {
    console.log("Update SFL error", error);
  }
);
Argument Type Description
options.SFLProductList array Array of List Item Input. Object containing parameters required for the list entry.
options.lid guid List id to add to
(This value is returned from the _swat.initializeSFLList call.)
successCb function Success callback function which will be called with the response
errorCb function Error callback function which will be called on unsuccessful response

In the example, updateSFL updates the cprops of a previously added product in the SFL list.

Get all products from SFL list

_swat.fetchSFLList(options, successCb, errorCb)

Example request

window._swat.fetchSFLList(
  { listId: "67c06a80-f103-403c-80f8-a450e964d9f6" },
  function (response) {
    console.log("Fetched SFL List", response);
  },
  function (error) {
    console.log("Fetch SFL List error", error);
  }
);

Example response

{
  "list": {
    "di": "b17aa994-cedf-46c1-9e9f-f7a5892976c7",
    "lty": "sfl",
    "uid": null,
    "cts": 1656584245700,
    "lnote": null,
    "lname": "My SFL List",
    "cby": null,
    "lid": "67c06a80-f103-403c-80f8-a450e964d9f6",
    "pid": "KABSbuGyYCuM6/IV7e7cGxT1978LieU1jRdMt6XhYfo=",
    "st": 1,
    "cprops": {},
    "id": "3483ea0c-071c-4a6f-83ea-0c071c5a6f99",
    "uts": 1656584245700,
    "ldesc": {},
    "uby": null,
    "cfor": null
  },
  "items": [
    {
      "di": "b17aa994-cedf-46c1-9e9f-f7a5892976c7",
      "bt": "Swym Marketing",
      "clbls": [],
      "uid": null,
      "dt": "1 LIGHT PENDANT",
      "cts": 1657183125325,
      "empi": 7096252727494,
      "cby": null,
      "lid": "67c06a80-f103-403c-80f8-a450e964d9f6",
      "du": "https://demo.swym.it/products/1-light-pendant",
      "pid": "KABSbuGyYCuM6/IV7e7cGxT1978LieU1jRdMt6XhYfo=",
      "epi": 41254709264582,
      "cprops": {
        "personalised": true
      },
      "id": "aba9cc40-5f57-4d93-a9cc-405f57ad93a0",
      "uts": 1657183125325,
      "iu": "https://cdn.shopify.com/s/files/1/0534/3635/0662/products/1LIGHTPENDANT_620x620.jpg?v=1637584280",
      "qty": 1,
      "uby": null,
      "pr": 150,
      "vi": null
    }
  ],
  "userinfo": null,
  "pagination": {
    "totalcount": 1,
    "next": null,
    "limit": null
  }
}

Fetch the list of products added to the user's SFL list. You can call this method once the window._swat object is initialized.

Argument Type Description
options.listId optional guid List id to add to
(This value is returned from the _swat.initializeSFLList call.)
successCb function Success callback function which will be called with the response
errorCb function Error callback function which will be called on unsuccessful response

Swym Back In Stock Alerts

Show "Email me when available" widget

Render "Email me when available" widget on a product page or any other page.

swat.addToWatchList(clickEvent, eventMap, callbackFn, renderIntoNodeopt)

 let product = {
  epi: variantId, // variant id
  empi: productID, // product id
  du: "https://canonicalproducturl", // canonical product url
  iu: "https://a.com/b.jpeg", // image url for email
  pr: 230, // price
  et : 8  // event type 8 stands for registering a "notify me" event.
 }

swat.addToWatchList(
  null, // clickEvent is optional
  product,   // product for which you want to subscribe for an alert
  function(response) {
    console.log("Successfully Opened the Pop up", response);
  },
  null // renderIntoNode is optional and can be used to render the form in a specific node 
);
Argument Type Description
clickEvent object event object of click listener event
evtMap object An object consisting epi, empi and iu
callbackFn function A callback function which will be called on success
renderIntoNodeoptional DOM node A DOM node where you want to show addToWatchlist as popup/inline form
topicoptional string A topic for which you want to subscribe for an alert (currently supported topics are "comingsoon" and "back-in-stock"); default is "back-in-stock"

Request Back In Stock Product Alerts for a product

_swat.sendWatchlist(mediumValue, sendMedium, eventObject, callbackFn, errorFn, addToMailingListopt)

Sends an back-in-stock alert request to the Swym platform.

swat.sendWatchlist(
  "demo@demo.com",
  "email",
  {
    epi: 123,
    empi: 12,
    du: "https://canonicalproducturl",
    iu: "https://a.com/b.jpeg",
    pr: 23
  },
  function(r) { console.log(r) },
  function(e) { console.log(e) },
  1
);
Argument Type Description
mediumValue string Value of the medium (currently supported ‘email’, hence email Id)
medium string What id is collected (currently 'email' supported)
product object Object with keys - {"epi" (variant id), "empi" (product master id), "du" (canonical product url), "iu" (image url), "pr" (price)}
callbackFn function Function that gets called after a successful HTTP API call
errorFn function Function that gets called when an error occurs
addToMailingListoptional int Possible values: 1(opted in) or 0(opted out), to tell if user will be added to the mailing list (Note:- requires mailing list feature to be set up from Swym's end)

Request product alerts for - product with specific topic

_swat.subscribeForProductAlert(mediumValue, medium, product, successFn, errorFn, addToMailingList, topic)

Send a product alert for a given topic. An alert email will be sent to subscriptions made using this API when given topic condition is fulfilled.

swat.subscribeForProductAlert(
  "demo@demo.com",
  "email",
  {
    epi: 123,
    empi: 12,
    du: "https://canonicalproducturl",
    iu: "https://a.com/b.jpeg",
    pr: 23
  },
  function(response) { console.log(response) },
  function(error) { console.log(error) },
  0,
  "comingsoon"
);
Argument Type Description
mediumValue string Value of the medium (currently supported ‘email’, hence email Id)
medium string What id is collected (currently 'email' supported)
product object Object with keys - {"epi" (variant id), "empi" (product master id), "du" (canonical product url), "iu" (image url), "pr" (price)}
successFn function Function that gets called after a successful API call
errorFn function Function that gets called when an error occurs
addToMailingList int Possible values: 1(opted in) or 0(opted out), to tell if user will be added to the mailing list (Note:- requires mailing list feature to be set up from Swym's end)
topic string topic like "comingsoon", defaults to "backinstock" if not provided

Lists Comments API

Add a comment to a list

swat.addComment(opts, successCallback, errorCallback)

swat.addComment(
  {
    listcomments: [
      {
        "txt": "Some new comment",
        "lid": "list-id"
      }
    ]
  },
  function(r) {
    console.log(r);
  },
  function(xhrObject) {
    // something went wrong
  }
);

Example Response - The added List comment

{
  "listcomments": [
    {
      "cid": "comment-id",
      "txt": "Some new comments",
      "lid": "list-id",
      "cts": 145555555511
    }
  ],
  "listitemcomments": []
}

Add a comment to a list

Argument Type Description
opts Object An options object with a List Comment Input array
opts.listcomments array An array of List Comment Input
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Add a comment to a list item

_swat.addComment(opts, successCallback, errorCallback)

swat.addComment(
  {
    listitemcomments: [
      {
        "txt":"Some item comment",
        "empi":123,
        "epi":111,
        "lid":"list-id"
      }
    ]
  },
  function(r) {
    console.log(r);
  },
  function(xhrObject) {
    // something went wrong
  }
);

Example Response - The added List Item comment

{
  "listcomments": [],
  "listitemcomments": [
    {
      "cid": "comment-id",
      "txt": "Some new comments",
      "lid": "list-id",
      "empi": 123,
      "epi": 111,
      "cts": 145555555511
    }
  ]
}

Add a comment to a list item

Argument Type Description
opts Object An options object with a List Item Comment Input array
opts.listitemcomments array An array of List Item Comment Input
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Fetch list comments

swat.fetchListComments(opts, successCallback, errorCallback)

swat.fetchListComments(
  {
    // List Id
    lid: "list-id"
    // limit: 8 // Optional Limit on number of comments to return
    // sincets: timeinmilliseconds // Optional The timestamp from when returned comments should begin
    // continuation: continuationtoken // Optional Continuation token passed back in the response
  },
  function(r){
    console.log(r);
  }, 
  function(xhrObject) {
    // something went wrong
  }
);

Example Response - Map containing continuation token and List Comments

{
  "continuation": null,
  "results": [
    {
      "cid": "comment-id",
      "userinfo": {
        "em": "email-id",
        "fname": "first name",
        "lname": "last name"
      },
      "txt": "My third comment is here",
      "lid": "list-id",
      "cts": 145555555511
    }
  ]
}
Argument Type Description
opts.lid string List id to fetch comments for
opts.limitoptional number Number of comments to fetch. Defaults to 100
opts.continuationoptional string Continuation token to paginate with the initial limit, returned in response. Null when limit is not hit
opts.sincetsoptional number Timestamp in milliseconds to fetch comments since
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Fetch list item comments

swat.fetchListItemComments(opts, successCallback, errorCallback)

swat.fetchListItemComments(
  {
    // List Id
    lid: "list-id",
    empi: 123,
    epi: 111
    // limit: 8 // Optional Limit on number of comments to return
    // sincets: timeinmilliseconds // Optional The timestamp from when returned comments should begin
    // continuation: continuationtoken // Optional Continuation token passed back in the response
  },
  function(r){
    console.log(r);
  },
  function(xhrObject) {
    // something went wrong
  }
);

Example Response - Map containing continuation token and List Item Comments

{
  "continuation": null,
  "results": [
    {
      "cid": "comment-id",
      "userinfo": {
        "em": "email-id",
        "fname": "first name",
        "lname": "last name"
      },
      "txt": "My third comment is here",
      "lid": "list-id",
      "empi": 123,
      "epi": 111,
      "cts": 145555555511
    }
  ]
}
Argument Type Description
opts.lid string List id of the list item
opts.empi string Product master id of the list item to fetch comments for
opts.epi string Product variant id of the list item to fetch comments for
opts.limitoptional number Number of comments to fetch. Defaults to 100
opts.continuationoptional string Continuation token to paginate with the initial limit, returned in response. Null when limit is not hit
opts.sincetsoptional number Timestamp in milliseconds to fetch comments since
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Delete a comment

_swat.deleteComment(opts, successCallback, errorCallback)

swat.deleteComment(
  {
    comments: [{
      "lid":"list-id",
      "cid":"comment-id"
    }]
  },
  function(r) {
    console.log(r);
  },
  function(xhrObject) {
    // Something went wrong
  }
);

Example Response - Array of deleted comments (#fields-in-list-comments-response)

{
  "d": [
    {
      "lid": "list id",
      "cid": "comment id"
    }
  ]
}

Delete a comment from a list or list item

Argument Type Description
opts Object An options object with array of comment delete input[#list-comment-delete-input]
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

REST APIs

Getting Started - Configuration.

API Configuration


pid - Unique identifier for your store

APIKey - API key for your store

Swym API Endpoint - Base URL for requests

Swym APIs are also available as REST endpoints. You can use these endpoints to integrate functionalities of the Swym platform into mobile apps, embedded devices, third-party software, etc.

You can login to the dashboard.Swym Dashboard to get the credentials for your store.

  1. pid - This is a unique identifier for your store. You can find this information on your Swym Dashboard, or contact our support.
  2. APIKey - You can request an API key for your store by logging into the Swym Dashboard > Integrations > REST API
  3. Swym API Endpoint - The secure Swym API endpoint for you store. This is determined by the tier on which your store is provisioned on the Swym platform, will be generated at the time your APIKey is provisioned.

Authentication

Swym REST APIs have two authentication modes depending on the API type.

# Using Basic auth
curl '{{Swym API Endpoint}}/storeadmin/me' \
  --basic \
  --user {{pid}}:{{APIKey}} \
  --compressed
# Using Authorization header
curl '{{Swym API Endpoint}}/storeadmin/me' \
  -H 'Authorization: Basic {{BASE64-ENCODING-OF-"pid:apikey"}}' \
  --compressed

Store Admin - Authentication.

Store Admin APIs follow Basic Authentication. In the Authorization header of your request, you will need username and password.

Field Value
username pid
password APIKey

End User / Shopper - Authentication

Storefront Shopper APIs use Swym RegId token for authentication. This requires adding below params in every request

curl '{{Swym API Endpoint}}/{{storefront endpoint}}?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --compressed
Field Parameter Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id

Generating headless session id

Sample random guid generator for session id.

function generateSessionId(len){
  var outStr = "", newStr;
  while (outStr.length < len)
  {
    newStr = Math.random().toString(36 /*radix*/).slice(2 /* drop decimal*/);
    outStr += newStr.slice(0, Math.min(newStr.length, (len - outStr.length)));
  }

  return outStr.toLowerCase();
}

In case of headless implementations, the caller can map shopper activity to an active session. Then the sessionid can be generated on the caller.

Any active session should expire after 30 mins of inactivity. This can used to record activity for a shopper back to a sessionid for dowstream logging and reporting.

Check API access

# With Basic auth
curl '{{Swym API Endpoint}}/storeadmin/me' \
  --basic \
  --user {{pid}}:{{APIKey}} \
  --compressed
# With Authorization header
curl '{{Swym API Endpoint}}/storeadmin/me' \
  -H 'Authorization: Basic {{BASE64-ENCODING-OF-"pid:apikey"}}' \
  --compressed

Example Response

{
  "pid": "yourstorepid",
  "appId": "StoreadminApi"
}

Use this API to check api key details.

HTTP Request

GET {{Swym API Endpoint}}/storeadmin/me

Generate Swym RegId

# Query params should be url encoded
curl '{{Swym API Endpoint}}/storeadmin/user/generate-regid?useremail={{url encoded useremail}}' \
  -H 'Authorization: Basic {{BASE64-ENCODING-OF-"pid:apikey"}}' \
  # or use --basic --user {{pid}}:{{APIKey}} \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'useragenttype=mobileApp' \
  --compressed

Example response

{
  "regid": "regidvalue",
  "sessionid": "sessionidvalue"
}

Use this API to generate a Swym RegId (unique key) for shopper email id. The generated regid should be used to make further API calls for accessing the shopper's context.

HTTP Request

POST {{Swym API Endpoint}}/storeadmin/user/generate-regid

Parameters

Field Type Description
pid string Unique identifier for your store
apikey string API Key generated for your store
useremail query The shopper's email address
useragenttype form data The type of client making this request. Eg: can be "mobileApp" if a mobile app is making the request.

Create list for a shopper

curl '{{Swym API Endpoint}}/api/v3/lists/create?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --data-urlencode 'lname={{lname}}' \
  # include other {{New List fields}}
  --compressed

Example response - Created List

{
  "uid": "example-uid",
  "cts": 1585080432834,
  "lname": "list_id 15",
  "cby": "example@example.org",
  "lid": "31b8fa07-example-ex-ex-ex",
  "pid": "example-providerid",
  "st": 1,
  "uts": 1585080432834,
  "uby": "example@example.org",
  "cfor": "example@example.org",
  "cnt": 1
}

Creates list with name and attributes for a shopper.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/create

Parameters

Parameter Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id
New List fields form data List Config. Expand each attribute as a form data field

Update list for a shopper

curl '{{Swym API Endpoint}}/api/v3/lists/update?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --data-urlencode 'lid={{lid}}' \
  # include other {{List Update fields}}
  --compressed

Example response - Updated List

{
  "uid": "example-uid",
  "cts": 1585080432834,
  "lname": "list_id 15",
  "cby": "example@example.org",
  "lid": "31b8fa07-example-ex-ex-ex",
  "pid": "example-providerid",
  "st": 1,
  "uts": 1585080432834,
  "uby": "example@example.org",
  "cfor": "example@example.org",
  "cnt": 1
}

Update a shopper's list attributes like lnote , lprops.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/update

Parameters

Parameter Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id
List Update fields form data List Update Input. Expand each attribute as a form data field

Delete list for a shopper

curl '{{Swym API Endpoint}}/api/v3/lists/delete-list?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --data-urlencode 'lid={{lid}}' \
  --compressed

Example response - Deleted List

{
  "uid": "example-uid",
  "cts": 1585080432834,
  "lname": "list_id 15",
  "cby": "example@example.org",
  "lid": "31b8fa07-example-ex-ex-ex",
  "pid": "example-providerid",
  "st": 1,
  "uts": 1585080432834,
  "uby": "example@example.org",
  "cfor": "example@example.org",
  "cnt": 1
}

Delete a shopper's list. The list contents will be deleted as well.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/delete-list

Parameters

Parameter Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id
listId guid List id to delete

Fetch lists for a shopper

curl '{{Swym API Endpoint}}/api/v3/lists/fetch-lists?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --compressed

Example response - Array of Lists

[{
  "uid": "example-uid",
  "cts": 1585080432834,
  "lname": "list_id 15",
  "cby": "example@example.org",
  "lid": "31b8fa07-example-ex-ex-ex",
  "pid": "example-providerid",
  "st": 1,
  "uts": 1585080432834,
  "uby": "example@example.org",
  "cfor": "example@example.org"
}]

Gets all lists owned by the current shopper.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/fetch-lists

Parameters

Field Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id

Fetch details for a shopper's list

curl '{{Swym API Endpoint}}/api/v3/lists/fetch-list-with-contents?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --data-urlencode 'lid={{lid}}' \
  --compressed

Example Response - Map containing List and an array of List Items

{
  "list": {
    "uid": "example-uid",
    "cts": 1585080432834,
    "lname": "list_id 15",
    "cby": "example@example.org",
    "lid": "31b8fa07-example-ex-ex-ex",
    "pid": "example-providerid",
    "st": 1,
    "uts": 1585080432834,
    "uby": "example@example.org",
    "cfor": "example@example.org",
    "cnt": 1
  },
  "items": [
    {
      "epi": 111,
      "empi": 123,
      "cprops": {},
      "note": null,
      "qty": 2,
      "lid": "31b8fa07-ex-ex----",
      "cby": "example@example.org",
      "cts": 1585080751632
    }
  ]
}

Used to fetch list details along with list items for a given list id.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/fetch-list-with-contents

Parameters

Parameter Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id
lid guid List id to fetch contents

Manage products in a shopper's list

curl '{{Swym API Endpoint}}/api/v3/lists/update-ctx?pid={{url encoded pid}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'regid={{regid}}' \
  --data-urlencode 'sessionid={{sessionid}}' \
  --data-urlencode 'lid={{lid}}' \
  --data-urlencode 'a=[{"empi": 111,"epi": 1111,"du": "producturl1"}]' \
  --data-urlencode 'u=[{"empi": 222,"epi": 2222,"du": "producturl2"}]' \
  --data-urlencode 'd=[{"empi": 333,"epi": 3333,"du": "producturl3"}]' \
  --compressed

Example response

{
  "a": [
    {
      "epi": 1111,
      "empi": 111,
      "cprops": {},
      "note": null,
      "qty": 1,
      "lid": "31b8fa07-ex-ex----",
      "cby": "example@example.org",
      "cts": 1585080751632
    }
  ],
  "d": [
    {
      "epi": 2222,
      "empi": 222,
      "cprops": {},
      "note": null,
      "qty": 1,
      "lid": "31b8fa07-ex-ex----",
      "cby": "example@example.org",
      "cts": 1585080751632
    }
  ],
  "u": [
    {
      "epi": 3333,
      "empi": 333,
      "cprops": {},
      "note": null,
      "qty": 1,
      "lid": "31b8fa07-ex-ex----",
      "cby": "example@example.org",
      "cts": 1585080751632
    }
  ]
}

Use this API to add, update, delete multiple products in a shopper's list. A maximum of 10 items can be modified in one call. Note that the response time could be longer depending on the number of list item inputs.

HTTP Request

POST {{Swym API Endpoint}}/api/v3/lists/update-ctx

Parameters

Parameter Type Description
pid query Unique identifier for your store
regid form data Swym RegId token generated for a shopper using Generate RegId
sessionid form data Session id generated with Generate RegId or headless session id
lid guid List id to fetch contents
a array Array of List Item definitions to add
u array Array of List Item definitions to update
d array Array of List Item definitions to delete

Response fields

Field Type Description
a array Array of list items added to the list
u array Array of list items updated on the list
d array Array of list items deleted from the list

Subscribe to Back In Stock Product Alert for a product

Using the subscriptions/create API, you can subscribe a user to Back In Stock Product Alert / or a custom topic of your choice.

Note: We do not pre-stock, pre-quantity check, or pre-validate product topics on our backend for subscriptions created from this API. You will need to make sure that the user can only subscribe to alerts for a product that's out of stock or based on topic before making a request.

curl -X POST '{{Swym API Endpoint}}/storeadmin/bispa/subscriptions/create' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{ BASE 64 Encrypted APIKEY : PID}}' \
--data-urlencode 'products=[{"epi":37993071378625, "empi":6229447573697, "du":"https://www.demo.swym.it/products/butterfly-sharon-cummings"}]' \
--data-urlencode 'medium=email' \
--data-urlencode 'mediumvalue=useremail@gmail.com'
--data-urlencode 'topics=["backinstock, comingsoon"]'
--data-urlencode 'addtomailinglist=1'

Example response:

{
 "message":"Successful",
 "products":[{"epi":37993071378625, "empi":6229447573697, "du":"https://www.demo.swym.it/products/butterfly-sharon-cummings"}],
 "topics":["backinstock"]
}

Authorization

Back In Stock Product Alerts API's follows Basic Authentication. In the Authorization header of your request, Please Check Authentication - Store Admin APIs - for more info.

Your Authentication keys will be generated and configured by swym support team post install. Enable Rest API's by navigating to Swym App Dashboard > Integrations > REST APIs

Request Body

Field Value Description Requirement
medium email subscription medium *mandatory
mediumvalue user email (demo@swymcorp.com) email address of the user. *mandatory
products Array[object] Array of key value pairs Back In Stock Product Alert Schema for which the user needs to be subscribed for alerts. *mandatory
topics Array[Strings] Subscription topic for a user, defaults to [backinstock]
addtomailinglist number (0 / 1) Subscribe user to mailing list 0 is opt out and 1 is opt in (optional)

Back In Stock Product Alert Schema

Example product schema:

products=[{"epi":37993071378625, "empi":6229447573697, "du":"https://www.demo.swym.it/products/butterfly-sharon-cummings"}]

Below are the mandatory keys-values or product schema for a Back In Stock Product Alert Subscription products array.

Key Type Description Requirement
epi number product variant id *mandatory
empi number product Id / product master Id *mandatory
du string cannonical URL of the product *mandatory

Reference - Lists

List Config

var listConfig = {
  "lname": "Todo List", // list name
  "lty": "wl", // List type  wl - wishlist, sfl - save for later
  "fromlid": "list Id", // list id to duplicate from
  "lnote": "This list is for my todo list", // optional note
  "lprops": {} // optional. Map of custom fields
};

REST API parameters to include in create list API

--data-urlencode 'lname={{lname}}' \
--data-urlencode 'lty={{lty}}' \
--data-urlencode 'fromlid={{fromlid}}' \
--data-urlencode 'lnote={{lnote}}' \
--data-urlencode 'lprops={{JSON stringified lprops}}' \

A simple Javascript object containing parameters required for creating a new list.

Argument Type Description
listConfig.lname string List name - unique for a given user, allows 3-50 characters (Required)
listConfig.ltyoptional string specifies the type of list you want to create, wl - wishlist, sfl - save for later, this is used to create a different type of list separate from the wishlist
listConfig.fromlidoptional string List id to duplicate from, lname has to be different from original list
listConfig.lnoteoptional string Optional note
listConfig.lpropsoptional object Optional. Map of custom fields

List Update Input

var listUpdateDef = {
  "lid": "list Id",
  "lname": "List name",
  "lnote": "List note",
  "lprops": {}
};

REST API parameters to include in update list API

--data-urlencode 'lid={{lid}}' \
--data-urlencode 'lname={{lname}}' \
--data-urlencode 'lnote={{lnote}}' \
--data-urlencode 'lprops={{JSON stringified lprops}}' \

Object containing params required for updating existing list

Argument Type Description
listUpdateDef.lid string List id to be updated
listUpdateDef.lname string List name
listUpdateDef.lnoteoptional string Optional note
listUpdateDef.lpropsoptional object Optional. Map of custom fields

Fields in list

{
  "lid": "swym generated list ID",
  "lname": "List name. List names need not be unique, i.e. If uniqueness is needed API caller should ensure dupes are not",
  "lty": "_recommends", //To prevent mixing with enduser created wishlists
  "lnote": "Optional. List note, single line of note at the list level",
  "lprops": {}, //Optional. Map or properties - {}. Not available downstream for reporting or segmentation queries
  "anonRead": "Optional. Default - false. Boolean flag if anonymous read is allowed for the given List ID",
  "cnt": 0,
  "_cp": false,
  "cby": "Created by email address",
  "uby": "Updated by email address",
  "cts": "Created at in milliseconds",
  "uts": "Updated at in milliseconds",
  "userinfo": {}
}

Fields in list

Argument Type Description
lid string Swym App generated unique GUID for each list
lname string List name - unique for a given user
listcontents array Preview array of list items
ltyoptional string List type - when null, it represents wishlist. When set to a value eg: _saveForLater, gets added to a different type of list separate from the wishlist
lnoteoptional string Optional note
lpropsoptional object Optional. Map of custom fields
anonReadoptional boolean Optional. True if the list can be read anonymously with lid
cnt number Number of items in list
_cpoptional boolean Optional. True if list duplication is in progress, copying the list items for large lists
cts number Created time at in milliseconds
utsoptional number Last updated time at in milliseconds
cbyoptional string Email address of the user if known when list was created
ubyoptional string Email address of the user if known when list was last updated
userinfooptional object User info of the list owner if user is known
userinfo.em string Email address of the owner
userinfo.fname string First name of the owner
userinfo.lname string Last name of the owner

Reference - List Contents

List Item Input

var listItemMap = {
  epi: epi, // one unique list item (empi+epi) per listid
  empi: empi,
  du: du,
  qty: qty,
  note: note, //optional
  cprops: {} // Optional custom attributes
};

REST API parameters to include in manage list items API

--data-urlencode 'epi: {{epi}}' \ # One unique list item (empi+epi) per listid
--data-urlencode 'empi: {{empi}}' \ 
--data-urlencode 'du: {{du}}' \
--data-urlencode 'qty: {{qty}}' \
--data-urlencode 'note: {{note}}' \
--data-urlencode 'cprops: {{JSON stringified cprops}}' \ # Optional custom attributes

Object containing params required for creating, updating or deleting list items

Argument Type Description
listItemMap.epi number/string Variant id of the product
listItemMap.empi number/string Product id of the product
listItemMap.du string Canonical uri of the product
listItemMap.qty optional number Defaults to 1. Quantity included for the action
listItemMap.note optional string Optional note
listItemMap.cprops optional object Optional. Map of custom fields
listItemMap.lbls optional array [string] Optional. Array of strings indicating labels, rooms, etc. for HTC. Only one value supported in array. eg: ["Room1"]
listItemMap._av optional bool Optional. true if the list action was done without user explicitly picking a variant. Can be used by Wishlist UX to require user to pick variant before adding to cart

Fields in List Item

{
  "lid": "List id",
  "epi": "Product Variant ID, unique per item within a list",
  "empi": "Product ID",
  "du": "Canonical uri of the product",
  "dt": "Product title",
  "qty": "Quantity",
  "pr": "Product price",
  "iu": "Product Image url",
  "note": "Item level note, single line of note at the list item level",
  "cprops": {},
  "bt": "Brand name",
  "ct": "Category/collection name",
  "vi": "Selected variant info",
  "_av": false,
  "cby": "Created by email address",
  "uby": "Updated by email address",
  "cts": "Created at milliseconds",
  "uts": "Updated at milliseconds"
}

Fields in List Item

Argument Type Description
lid string List id - system generated guid for the list
epi number/string Variant id of the product
empi number/string Product id of the product
du string Canonical uri of the product
dt string Product title
qty number Quantity, defaults to 1
pr float Product Price
iu string Product image url
noteoptional string Optional. note
cpropsoptional object Optional. Map of custom fields
btoptional string Optional. Brand name
ctoptional string Optional. Category/collection name
vioptional string Optional. Selected variant info
_avoptional bool Optional. true if the list action was done without user explicitly
cts number Created time at in milliseconds
utsoptional number Last updated time at in milliseconds
cbyoptional string Email address of the user if known when list item was created
ubyoptional string Email address of the user if known when list item was last updated

Reference - Comments

List Comment Input

var listCommentDef = {
  "lid": "list id", 
  "txt": "Comment text",
  "cprops": {} // optional param
};

Object containing params required for creating new list comment

Argument Type Description
listCommentDef.lid string List id to add comment
listCommentDef.txt string Comment content
listCommentDef.cpropsoptional object Optional. Map of custom fields

List Item Comment Input

var listItemCommentDef = {
  "lid": "list id", 
  "empi": "Product master id",
  "epi": "Product variant id",
  "txt": "Comment text",
  "cprops": {} // optional param
};

Object containing params required for creating new list item comment

Argument Type Description
listItemCommentDef.lid string List id for the list item
listItemCommentDef.empi number/string Product master id of the list item to add comment
listItemCommentDef.epi number/string Product Variant id of the list item to add comment
listItemCommentDef.txt string Comment content
listItemCommentDef.cpropsoptional object Optional. Map of custom fields

List Comment Delete Input

var listCommentDeleteDef = {
  "lid": "list Id",
  "cid": "comment id"
};

Object containing params required for deleting a comment

Argument Type Description
listCommentDeleteDef.lid string List id of the comment
listCommentDeleteDef.cid string Comment id to be deleted

Fields in List Comments Response

{
  "cid": "System generated comment id",
  "lid": "List id for the comment",
  "txt": "Comment text",
  "via": "set as 'email' if comment received via email",
  "cby": "Created by email address",
  "uby": "Updated by email address",
  "cts": "Created at in milliseconds",
  "userinfo": {} // userinfo for the comment adder
}

Fields in List Comment Response

Argument Type Description
cid string Comment id - system generated guid for the comment
lid string List id - system generated guid for the list
txt string Comment content
viaoptional string set as email if comment was received via email, else undefined
cpropsoptional object Optional. Map of custom fields
cts number Created time at in milliseconds
cby string Email address of the user who added the comment
userinfo Object User info of the comment adder
userinfo.em string Email address of the adder
userinfo.fname string First name of the adder
userinfo.lname string Last name of the adder

Fields in List Item Comments Response

{
  "cid": "System generated comment id",
  "lid": "List id for the comment",
  "empi": "Product ID",
  "epi": "Product Variant ID",
  "txt": "Comment text",
  "via": "set as 'email' if comment received via email",
  "cby": "Created by email address",
  "uby": "Updated by email address",
  "cts": "Created at in milliseconds",
  "userinfo": {} // userinfo for the comment adder
}

Fields in List Item Comment Response

Argument Type Description
cid string Comment id - system generated guid for the comment
lid string List id - system generated guid for the list
epi number/string Variant id of the product
empi number/string Product id of the product
txt string Comment content
viaoptional string set as email if comment was received via email, else undefined
cpropsoptional object Optional. Map of custom fields
cts number Created time at in milliseconds
cby string Email address of the user who added the comment
userinfo Object User info of the comment adder
userinfo.em string Email address of the adder
userinfo.fname string First name of the adder
userinfo.lname string Last name of the adder

Render UI within containers

The Render APIs are used to render the Swym User Interface, like a wishlist page, shared wishlist, or other default implementations available in the Swym Javascript SDK, within a container element on the storefront.

The container element can be a div, section, page, or any other HTML element. The default UI elements will be rendered within the container element.

Render a Wishlist UI in a container

Render the wishlist default UI based on the respective API will be rendered within a container element on the storefront. This can be used to render the wishlist as a page or as a modal.

swat.ui.renderWishlistInContainer(containerElement, queryParams)

<!-- Include html in the body -->
<div id="swym-wishlist-render-container"></div>
window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {
  var wishlistContainerElement = document.querySelector("#swym-wishlist-render-container");
  var queryParams = swat.utils.getEncodedAsObject(window.location.search);
  // Contains queryParams["lid"] to render a specific list id
  swat.ui.renderWishlistInContainer(wishlistContainerElement, queryParams);
});

Create a page on the storefront with required HTML element and use the API to initialize the UI render within a SwymCallback. The URL to this page can be the wishlist as a page for the storefront

Argument Type Description
wishlistContainerElement DOMElement Target element to render User interface into
queryParams Object Query string as object, lid key to set list id to open

Render the Shared Wishlist UI Container

Create a page on the storefront with required HTML element and use the API to initialize the UI render within a SwymCallback. The URL to this page can be the shared wishlist landing page for the storefront. This URL will be passed a hkey or lid in the query parameter which will need to be passed to the API.

swat.ui.renderSharedWishlistInContainer(containerElement, sharedHkey, queryParams)

<!-- Include html in the body -->
<div id="swym-shared-wishlist-render-container"></div>
window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {
  var queryParams = swat.utils.getEncodedAsObject(window.location.search);
  var sharedHkey = queryParams["hkey"] || queryParams["lid"];
  var sharedWishlistContainerElement = document.querySelector("#swym-shared-wishlist-render-container");
  swat.ui.renderSharedWishlistInContainer(sharedWishlistContainerElement, sharedHkey, queryParams);
});
Argument Type Description
wishlistContainerElement DOMElement Target element to render into
sharedHkey String Shared hashkey to a list, usually a list id
queryParams Object Query string as object

Render an unsubscribe form

swat.unsubscribeFromSwym(unsubMap, successCallback, errorCallback)

Unsubscribe page is to be hosted on the storefront. The page receives query params in the URL to specify the user context, product context the unsubscribe came from.

window.SwymCallbacks = window.SwymCallbacks || [];
window.SwymCallbacks.push(function(swat) {
  var params = SwymUtils.getEncodedAsObject(window.location.search);
  var reqdParams = ["smid", "email", "epi", "empi", "appname", "du"];
  // Use required params like appname, du etc. to render the form with more information about the user and product to be unsubscribed
  var unsubMap = {
    smid: params.smid,
    mediumvalue: params.email,
    productid: params.epi // If it needs to be specific to the product
  };

  swat.unsubscribeFromSwym(unsubMap, function() {
    console.log("Unsubscribed successfully");
  }, function() {
    console.error("Unsubscribe failed");
  });
});
Argument Type Description
unsubMap object Object containing params required to unsubscribe
unsubMap.mediumvalue string Medium value to unsubscribe
unsubMap.mediumoptional string Optional, Medium to unsubscribe from, Default: email
unsubMap.productidoptional number/string Variant id of the product to unsubscribe
unsubMap.smidoptional guid Message id to unsubscribe
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response.

Errors

Ideally, there should not be any errors while calling these APIs. In case you encounter any such interruptions in the flow, please check the console of your web page and see if the error is coming from our end. Our Javascript APIs will leave a handy error message on the developer console if the error is caught at our level.

If you do see an error that isn't self-explanatory, please reach out to our developers’ team. In any case, we are monitoring our APIs. So, if any exceptions or errors are generated, we can check the logs and fix them for you even before you encounter them.

For the errors coming from the server, the Swym JS APIs use the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- You are performing an action on a resource that is not granted to the current logged-in user. Additionally, for REST APIs, this could mean your API key is wrong.
403 Forbidden -- You are not allowed to request this data.
404 Not Found -- The specified requested data could not be found.
429 Too Many Requests -- You're raising too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Parsing Bad Request error

Example Bad Request response body

{
  "errors": {
    "lid": "missing-required-key",
    "lid2": "disallowed-key"
  },
  "value": {
    "lid2": "somevalue"
  },
  "in": [
    "request",
    "form-params"
  ]
}

The HTTP 400 Bad Request response indicates the field(s) that are incorrect.

The errors key returns the actual field names and the reason for the failure.