NAV Navbar

Introduction to v3.0

Configure API access

This document lists and explains various front-end javascript APIs and HTTP REST APIs exposed by Swym. Please use the search bar on your left to search for keywords on each API, In case of any incorrect or incomplete information, please reach out to support@swymcorp.com and we will get back to you

In this documentation, we have covered following topics for an individual API:

Changes from V2

If you are already using Swym JS APIs v2.0, below are changes consider

Initialization

function swymCallbackFn(swat) {
   // your API calls go here
   // use swat within this scope, 
   // alternatively you can use window._swat
}
if(!window.SwymCallbacks) {
 window.SwymCallbacks = [];
}
window.SwymCallbacks.push(swymCallbackFn);

Swym JS loads asynchronously to ensure it does not fall in site's critical loading path. To ensure all calls to Swym APIs are made only once Swym is loaded and ready, please wrap all calls to the API in a construct as shown on the right.

The SwymCallBacks array is a queue mechanism that executes post Swym application load. Push all your Swym API related code to this array and Swym will make sure that the Apps are fully loaded in the front-end before executing the functions in the order of precedence in the array.

Wishlist button

Add to wishlist

_swat.addToWishList(eventObject, callbackFn, noShowNotificationopt)

window._swat.addToWishList(
  {
    "epi": 123,
    "du": "https://yourstore.com/products/your-awesome-product",
    "empi": 1234,
    "iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
    "pr": 50,
    "et": 4,
    "stk": 100,
    "variants": [{"Blue / XL": 123}]
  },
  function(r) {
    console.log('Added to wishlist');
  }
);


// An example with cprops
window._swat.addToWishList(
  {
    "epi": 456,
    "du": "https://yourstore.com/products/your-another-awesome-product",
    "empi": 6789,
    "iu" : "//www.understandfrance.org/Images/AsterixObelix2.jpg",
    "pr": 70,
    "stk": 10,
    "et":4,
    "variants": [{"Yellow / XL": 123}],
    "cprops": {personalised: true}
  },
  function(r) {
    console.log('Added to wishlist');
  }
);


Adds a new wishlist event. Please refer to the example. 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 'Add to Wishlist', it is best to first check if the product or variant is already in the wishlist, by using the "fetch" API.

Please refer our blog/guide for directly connecting button to wishlist actions here - Wishlist Plus Customization Cheatsheet

Argument Type Description
epi int/string External product unique id (variant level if applicable)
empi int/string External product master id (if there is a group product id with different variant ids)
du string Canonical product url
iu string Image-uri - Without protocol so protocol can be decided while rendering to http or https
pr float Price
cpropsoptional object data object that can be used to pass any custom data about the event
For response function A callback function, which takes a single argument (JSON response from the swym service)
noShowNotification boolean Boolean for should the slide-out notification be shown. By default, this argument is false and the notification is shown

In the example, the request adds the product variant to the wishlist. Please note that the these parameters are mandatory ones (epi, empi, du and iu).

Remove from wishlist

_swat.removeFromWishList(eventObject, callbackFn)

Removes a previously added wishlist event. Please refer to the example. You can call this method once the window._swat object is initialized. This API can be used for the same scenarios as addToWishList.

window._swat.removeFromWishList(
  {
    "epi": 123,
    "du": "https://yourstore.com/products/your-awesome-product",
    "empi": 1234,
    "iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
    "pr": 50,
    "stk": 100,
    "variants": [{"Blue / XL": 123}]
  },
  function(r) {
    console.log('Removed to wishlist');
  }
);
Argument Type Description
epi int/string External product unique id (variant level if applicable)
empi int/string External product master id (if there is a group product id with different variant ids)
du string Canonical product url
iu string Image-uri - Without protocol so protocol can be decided while rendering to http or https
pr float Price
For response function A callback function, which takes a single argument (JSON response from the swym service)

In the example, removeFromWishList removes a previously added entry from the wish list.

Get wishlisted products

_swat.fetch(callbackFn)

Example request

window._swat.fetch( function(r) {
  console.log(r);
  document.getElementById('demo').innerHTML = r;
});

Example response

[
  {
    "di": "deviceid",
    "_id": "deviceid.ts",
    "date": "2017-01-16",
    "pt": "Your Awesome Product",
    "rc": "default",
    "variants": "[{\"Blue\":123}]",
    "dt": "Your Awesome Product - Blue",
    "et": 1,
    "raw-du": "https://yourstore/products/your-awesome-product?v=123",
    "act": true,
    "empi": 1234,
    "ts": 1111,
    "du": "https://yourstore/products/your-awesome-product?v=123",
    "pid": "yourstorepid",
    "epi": 123,
    "iu": "//yourstore.com/images/your-awesome-product-123",
    "dcat1": "Personal computer",
    "pr": 50,
    "ct": "Accessories",
    "dcat": "Mac",
    "type": "product-variant"
  },
  {
    "di": "deviceid",
    "_id": "deviceid.ts",
    "date": "2017-01-16",
    "pt": "Your Awesome Product",
    "rc": "default",
    "variants": "[{\"Red\":134}]",
    "dt": "Your Awesome Product - Red",
    "et": 4,
    "raw-du": "https://yourstore/products/your-awesome-product?v=134",
    "act": true,
    "empi": 1234,
    "ts": 11,
    "du": "https://yourstore/products/your-awesome-product?v=134",
    "pid": "yourstorepid",
    "epi": 134,
    "iu": "//yourstore.com/images/your-awesome-product-134",
    "dcat1": "Personal computer",
    "pr": 45,
    "ct": "Accessories",
    "dcat": "Mac",
    "type": "product-variant"
  }
]

Fetch the list of products added to the user's wishlist window._swat object is initialized.

Argument Type Description
callbackFn function A callback function with a single argument, which is a JSON response on success.

Update a wishlist item

_swat.updateWishlistEvent(eventsToUpdate, callbackFn, errorFn)

Allows updating cprops, note parameters for the list entry.

  var listItemMap = {
    epi: epi,  // unique epi per listid
    empi: empi,
    du: du,
    qty: qty,
    note: note, //optional
    cprops: {} // Optional custom attributes
  };

  swat.updateListItem(listId, listItemMap, function(updatedListItem){
    // successfully updated list item
    // TODO API response to be updated
    callback(updatedListItem);
  }, function(xhrObj) {
    // something went wrong
  });
Argument Type Description
listId guid List id to add to
listItemMap object Object containing params required for the list entry
listItemMap.epi int/string Variant id of the product to be added
listItemMap.empi int/string Product id of the product to be added
listItemMap.du string Canonical uri of the product to be added
listItemMap.qty int Defaults to 1. Quantity included for the add action
listItemMap.noteoptional string Optional note
listItemMap.cpropsoptional object Optional. Map of custom fields
successCallback function Success callback function which will be called with the response
errorCallback function Error callback function which will be called on unsuccessful response

Back In Stock Product Alerts

Show "Email me when available" widget

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

When a product is out of stock and you want to show "Email me when available" subscription button, we can use this API to add a product to user's "watchlist". Whenever product is back in stock, an email will be sent to user automatically if addToWatchlist was performed for that product for user.

window._swat.addToWatchList(
  clickEventObj,
  { epi: 10, empi: 10, et: 8, iu: "IMAGE_URL" },     // event type 8 stands for registering a "notify me" event.
  function(r) {
    console.log("response", r);
  },
  document.querySelector(".INJECT-FORM");
);
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

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.

window._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.

window._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

Multiple lists

The Swym platform supports having multiple (wish)lists for a user, eg: my lounge, my bedroom, etc. or in case of fashion eg: my outdoor collection, my summer list, etc. These APIs are available on the premium plans, please contact us to enable these APIs for your installation.

Create a new list

var newListDef = {
  "lname": "New List name",
};
// Add lprops if needed
// newListDef.lprops = {customVal1: "custom value"};
// Pass fromlid if that list needs to duplicated
// stParams.fromlid = "list id to duplicate from"; 

swat.createList(newListDef, function(newListObj){
  // successfully created list
  console.log("New list created with listid", newListObj.lid);
}, function(xhrObject) {
  // something went wrong
});

Creates list with name and attributes.

Argument Type Description
newListDef object List Definition Input. Object containing params required for creating new list
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 list details

swat.fetchListDetails(params, successCallback, errorCallback)

swat.fetchListDetails({lid: listId}, function(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
params.lid 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

Get products for a list

swat.fetchListDetails(params, successCallback, errorCallback)

swat.fetchListDetails({lid: lid}, function(listContents){

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

Example Response - Array of List Items

[
  {
    "epi": 111,
    "empi": 123,
    "cprops": {},
    "note": null,
    "qty": 2,
    "lid": "31b8fa07-ex-ex----",
    "cby": "example@example.org",
    "cts": 1585080751632
  }
]

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 product to a list

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

Add product to a list.

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
};

swat.addToList(listId, listItemMap, function(newListItem){
  // successfully added list item
  callback(newListItem);
}, function(xhrObj) {
  // something went wrong
});
Argument Type Description
listId guid List id to add to
listItemMap 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

Get all lists

swat.fetchLists(opts)

Gets all lists for the current user.

swat.fetchLists({
  callbackFn: function(lists) {

    console.log("Fetched my lists", lists.length);
  },
  errorFn: function(xhrObj) {
    // something went wrong
  }
});

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

Remove product from a list

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

Remove a product from a list.

var listItemMap = {
  epi: epi,  // unique epi per listid
  empi: empi,
  du: du
};

swat.deleteFromList(listId, listItemMap, function(deletedListItem){
  // successfully deleted list item
  callback(deletedListItem);
}, function(xhrObj) {
  // something went wrong
});
Argument Type Description
listId guid List id to delete from
listItemMap 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

Remove a list

swat.deleteList(listId, successCallback, errorCallback)

Removes a list

swat.deleteList(listIdToBeDeleted, 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

Add multiple products to a list

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

Adds multiple list items to a list

swat.addProductsToList(listId, listItemMaps, function(resp){

}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listId guid List id to add to
listItemMaps 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

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

Remove multiple list items to a list

swat.removeProductsFromList(listId, listItemMaps, function(resp){

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

Add product to multiple lists

swat.addProductToLists(listItemMap, listIds, successCallback, errorCallback)

Adds a list item to multiple lists

swat.addProductToLists(listItemMap, listIds, function(resp){

}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listItemMap object List Item Input. Object containing params required for the list entry
listIds 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

swat.removeProductFromLists(listItemMap, listIds, successCallback, errorCallback)

Remove multiple list items to a list

swat.removeProductFromLists(listItemMap, listIds, function(resp){

}, function(xhrObject) {
  // something went wrong
});
Argument Type Description
listItemMap object List Item Input. Object containing params required for the list entry
listIds array Array of List ids to remove from. 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

Update list attributes

swat.updateList(listUpdateMap, successCallback, errorCallback)

var listUpdateMap = {
  "lid": "list id to update, mandatory",
  "lname": "List name, mandatory",
  "lnote": "Updated List note, optional"
};
// Update lprops if needed
// 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

Social sharing of Wishlist (Premium)

Share wishlist on social media

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

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(
  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.

Generate shareable wishlist URL

swat.generateSharedListURL(listId, callbackFn, errCallBack)

A lower level API that returns the unique wishlist 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(
  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.

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

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

Connecting shopper account

Swym APIs allow a couple modes of connecting shopper account either via a native storefront login or a lightweight 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.

Render UI within containers

Render 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 wishlist as a page for the storefront

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);
});
Argument Type Description
wishlistContainerElement DOMElement Target element to render into
queryParams Object Query string as object, lid key to set list id to open

Render 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

Handle 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

HTC Comments API

Add a comment to a list

swat.addComment(opts, successCallback, errorCallback)

window._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)

window._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)

window._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 (Premium)

Getting started with APIs

API Configuration


pid - Unique identifier for your store

APIKey - API key for your store

Swym API Endpoint - Base URL for requests

In addition to our JavaScript SDK, Swym APIs are also available as REST endpoints. Developers can use these endpoints to integrate functionalities of the Swym platform in mobile apps, embedded devices, third-party software etc.

Before you start can start using these APIs, you will need

  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.

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

Authentication - Store Admin APIs

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

# 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
Field Value
username pid
password APIKey

Authentication - Storefront Shopper APIs

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 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 Definition Input. 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

v2 Fetch wishlist products for a user

curl -X GET \
  '{{Swym API Endpoint}}/storeadmin/user/wishlist?useremail=demouser@demo.com' \
  -H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
  -H 'Content-Type: application/x-www-form-urlencoded'

Example response:

{
  "metadata": [{
    "inactive": false,
    "vendor": "Pure Fix Cycles",
    "vval1": "50 cm",
    "iqty": 100,
    "empi": 1483962056779,
    "title": "Alfa",
    "prodtype": "Fixed Gear Bicycle",
    "sku": "The Alfa - Small",
    "du": "https://engagedemo.myshopify.com/products/the-alfa",
    "pid": "Muz0BmP2s4Nu+YhQLYhKKRqe11LtYYeC/2Ju3Z0yYqk=",
    "epi": 13585114988619,
    "id": "a4c07b32-cc59-4abd-807b-32cc598abd87",
    "iu": "https://cdn.shopify.com/s/files/1/2241/2845/products/ALFA_SIDE_WEB.jpg?v=1542443636",
    "uri": "https://engagedemo.myshopify.com/products/the-alfa?variant=13585114988619",
    "pr": 1981.77,
    "vkey1": "Size"
  }],
  "epis": [{
    "epi": 13585114988619,
    "ts": 1561451272218,
    "_id": "8c09ffe4-1262-4b6d-b203-98bd0ac593af.1561451272218",
    "date": "2019-06-25",
    "dcat": "Mac",
    "dcat1": "Personal computer",
    "di": "8c09ffe4-1262-4b6d-b203-98bd0ac593af",
    "et": 4
  }]
}

Example call with "cached-products" parameter:

curl -g -X GET \
  'https://YOUR_SWYM_ENDPOINT/storeadmin/user/wishlist?useremail=demouser@demo.com&cached-products=[{%22epi%22:%2013585114988619,%20%22_hv%22:%20%22Oi%2BZI8dGO%2Fd6bPkDuNzX61IGrc%2FPQPBOq9HmMfjy9iI%3D%22}]' \
  -H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
  -H 'Content-Type: application/x-www-form-urlencoded'

With this API, you can fetch all the wishlisted products for a shopper given email address.

The response here contains two important keys - metadata and epis. The epis key contains data about the wishlist event (when it happened, device info, etc) while the metadata key contains data about the product for which the event happened. While rendering with this data, loop over the epis key, take the epi (variant id) and merge it with its corresponding object in the metadata key (using the epi key in each object inside metadata key). This will give you a list that has complete data about a wishlist event.

To optimise data sent over the wire, this API also provides a "cached-products" parameter. This parameter determines the client's product metadata state. If the client already has the latest metadata about a product, it's not sent again for that product. Whenever metadata about a product is sent by a Swym API, "_hv" key is returned along with it. This key is the "freshness stamp" for a product. While making the next request, if the client sends the "cached-product" parameter with the variant id and the stamp for the product's metadata that the client has, Swym checks if the stamp represents the most recent state. If it does, Swym API will not return the product metadata again.

Field Type Description
useremail string The customer's email address
cached-products optional Array[object] Array of json objects containing the variant id and hash value of product data available to the client

v2 Add products to user's wishlist

curl -X POST \
  'https://YOUR_SWYM_ENDPOINT/storeadmin/user/add-wishlist?useremail=demouser@demo.com' \
  -H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d epis=%5B13585100865611%5D

Example response:

{"message":"Product(s) added to user collection"}

Using this API, you can add an array of products to a user's wishlist, given their email address.

Query Parameters

Field Type Description
useremail string The customer's email address
appId optional string the type of client making this request. Defaults to "StoreadminApi". Can be "mobileApp" if app is making the request.

Request Body

Field Type Description
epis Array[object] Array of variant ids of the products to be added to wishlist.

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 / pre validate product topic 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

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

Note : products and other request body items should be url encoded.

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

Example Input:

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

Reference - Lists

List Definition Input

var listDef = {
  "lname": "List name", 
  "lty": "List type",
  "fromlid": "fromlistId",
  "lnote": "List note",
  "lprops": {}
};

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}}' \

Object containing params required for creating new list

Argument Type Description
listDef.lname string List name - unique for a given user, allows 3-50 characters
listDef.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
listDef.fromlidoptional string List id to duplicate from, lname has to be different from original list
listDef.lnoteoptional string Optional note
listDef.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": "System 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 List id - system generated guid for the 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.qtyoptional number Defaults to 1. Quantity included for the action
listItemMap.noteoptional string Optional note
listItemMap.cpropsoptional object Optional. Map of custom fields
listItemMap._avoptional 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

Errors

Ideally there should not be any error while calling these APIs. In case if 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 it 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 for 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.
418 I'm a teapot.
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 is returns the actual field names and the reason for the failure.