Subscribe to Back in Stock Alert

Subscribe to Back In Stock Product Alert for a product using Create API

Introduction

By using the Create API, it's possible to subscribe shoppers to back in stock product alerts or custom topics of your choosing for a shopper.

Endpoint

Endpointrequest typeAPI Type
https://{{Swym API Endpoint }}/storeadmin/bispa/subscriptions/createPOSTshopper

Authorization

Back In Stock Product Alerts API's follows Basic Authentication. In the Authorization header of your request.

Headers:

HeaderRequiredSample valueDescription
user-agentYes"mobileApp"User-Agent header of the app used to access the API (mobileApp)
Content-TypeYesapplication/x-www-form-urlencodedMIME type, also known as a media type or content type, that is used to encode and transfer data over the internet.
AuthorizationYesBasic {{ BASE 64 Encoded PID : API KEY}}PID and API Key needs to be encoded to base 64 format.

Form Data

FieldTypeRequiredDescription
mediumstringrequiredmedium (email, sms)
mediumvaluestringrequiredemail / phone number of the Shopper.
productsstringrequiredStringified array of products to subscribe.
topicsarrayrequiredRead more about topics
addtomailinglistint64optionalSubscribe user to mailing list 0 is opt out and 1 is opt in
extrasstringoptionalExtra info if you have any, limited to 2048 characters.

Example Curl

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 {{BASE64-ENCODING-OF-"PID:API Key"}}' \
--data-urlencode 'products=[{"epi":37993071378625, "empi":6229447573697, "du":"https://www.demo.swym.it/products/butterfly-sharon-cummings"}]' \
--data-urlencode 'medium=email' \
--data-urlencode '[email protected]'
--data-urlencode 'topics=["backinstock"]'
--data-urlencode 'addtomailinglist=1'
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 {{BASE64-ENCODING-OF-"PID:API Key"}}' \
--data-urlencode 'products=[{"epi":37993071378625, "empi":6229447573697, "du":"https://www.demo.swym.it/products/butterfly-sharon-cummings"}]' \
--data-urlencode 'medium=email' \
--data-urlencode '[email protected]'
--data-urlencode 'topics=["backinstock","comingsoon"]'
--data-urlencode 'addtomailinglist=1'

🚧

Curl Placeholders

Assuming these values are provided above, the curl command should work correctly. However, if there are any issues with the API endpoint or the data being passed in the request, there could still be errors that need to be resolved before you can test these APIS.

PlaceholdersDescriptions
{{Swym API Endpoint}}This needs to be replaced with the actual Swym API endpoint URL.
{{API Key}}This needs to be replaced with the actual API Key
{{PID}}This needs to be replaced with the actual PID value.

Success Response

The below responses are what you would get based on subscribing to a single topic or for multiple topics.

{
   "message":"Successful",
   "products":[
      {
         "bt":"3M",
         "dt":"3M CGXL-GU General Purpose Extra Large Nitrile Palm Nylon Lining Comfort Grip Glove, Gray",
         "empi":8142224425277,
         "sku":"3MCGXLGU",
         "du":"https://demoswym.myshopify.com/products/3mcgxlgu",
         "pid":"+yFr2xLY3LCQ=",
         "stk":0,
         "epi":44645297750333,
         "iu":"https://cdn.shopify.com/s/files/1/0708/0139/1933/products/3MCGXLGU_620x620.jpg?v=1677090238",
         "uri":"https://demoswym.myshopify.com/products/3mcgxlgu?variant=44645297750333",
         "pr":10.0,
         "vi":""
      }
   ],
   "topics":[
      "backinstock"
   ]
}
{
   "message":"Successful",
   "products":[
      {
         "bt":"3M",
         "dt":"3M CGXL-GU General Purpose Extra Large Nitrile Palm Nylon Lining Comfort Grip Glove, Gray",
         "empi":8142224425277,
         "sku":"3MCGXLGU",
         "du":"https://demoswym.myshopify.com/products/3mcgxlgu",
         "pid":"+yFr2xLY3LCQ=",
         "stk":0,
         "epi":44645297750333,
         "iu":"https://cdn.shopify.com/s/files/1/0708/0139/1933/products/3MCGXLGU_620x620.jpg?v=1677090238",
         "uri":"https://demoswym.myshopify.com/products/3mcgxlgu?variant=44645297750333",
         "pr":10.0,
         "vi":""
      }
   ],
   "topics":[
      "backinstock",
      "comingsoon"
   ]
}

Error Response:

If the request is unsuccessful, the API will return a JSON response with an error message and an HTTP status code indicating the type of error that occurred.

Status CodeTypeDescription
400Bad RequestYour request is invalid, change your request params and query and try again.
401UnauthorisedYou 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.
403ForbiddenYou are not allowed to request this data.
404Not FoundThe specified requested data could not be found.
429Too Many RequestsYou're raising too many requests! Slow down!
500Internal Server Error --We had a problem with our server. Try again later.
503Service UnavailableWe're temporarily offline for maintenance. Please try again later.

Topic

In Swym's backend, "topics" are specific keywords that define a customer's journey. Each topic has an associated email template and predetermined logic with rules that you can assign and control. These rules can then be used to send emails to the user through the email templates, sms (medium).

Essentially, topics help to streamline the process of sending personalised and relevant emails or sms to customers based on their actions and behaviours on your website.

Here is a sample table to explain some topics used above.

Topic NameDescriptionUse CasesTrigger type
backinstockThe restock notification topic is specifically related to inventory levels. If a user wants to receive a product alert for when an item is back in stock, they need to be subscribed to this particular topic.Subscribe for an out of stock product alert.Automatic
comingsoonA tag based topic or a manual trigger topic where the product is not stock dependent as such of back in stockLet a shopper that a there was a product launchManual
custom topicyou may request custom topic, based on your requirement we may facilitate that provided it is related to this APIany custom use caseAutomatic / Manual.

👍

Email Service Provider Support.

We support integration with many third-party Email Service Providers (ESPs) to send alert details. To see the list of supported partners, please visit your Swym Admin Dashboard > Integrations

Other References

Product

To find and subscribe a product on your e-commerce platform, it's necessary to provide the following mandatory information for each item in the array:

Property NameData TypeRequiredDescription
product.epiint/stringYesVariant id of the product to be added
product.empiint/stringYesProduct id of the product to be added
product.dustringYesCanonical uri of the product to be added

Things to Consider

Inventory Updates.

❗️

Inventory must be handled by the platform.

it's necessary for your e-commerce platform, such as Shopify, Bigcommerce, or Magento, to manage your inventory. In other words, if your inventory is not managed by your e-commerce platform, this API will not be compatible with your system

Frontend Stock Checks.

❗️

Ensure Product Availability Before Requesting Subscriptions

Please note that our backend does not pre-stock, pre-quantity check, or pre-validate product topics for subscriptions created from this API. Therefore, it's important to ensure that users can only subscribe to alerts for products that are out of stock or based on topic before making a request.