Introduction
The Back In Stock Notification Requests API allows you to manage customer requests to receive notifications when out-of-stock items become available.
With this API, you can:
- Increase sales and customer satisfaction with personalized notifications.
- Collect insights on requested items that are currently unavailable.
- Effectively manage inventory and adjust restocking strategy.
Learn more about notifying customers when products are back in stock.
Before you begin
It’s important to note the following points before starting to code:
- To start collecting back in stock requests, the
collectionStates
must be set totrue
. UsestartCollectingRequests()
inBackInStockSettings
to update collection states. - Customize the design of the notification email that will be sent.
Terminology
- Back in stock notification request: The object that is created when a customer wants to be notified when an out-of-stock item becomes available. The back in stock notification request contains information about the item and an email address to contact when it’s back in stock.
Setup
To use the BackInStockNotifications API, install the @wix/ecom
package using npm or Yarn:
1npm install @wix/ecom
or
1yarn add @wix/ecom
Then import { backInStockNotifications }
from @wix/ecom
:
1import { backInStockNotifications } from '@wix/ecom'
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a back in stock notification request.
If a notification request already exists for the same catalogReference
and email
,
then a new one isn't created and the existing request is returned.
Permission Scopes
For app development, you must have one of the following permission scopes:function createBackInStockNotificationRequest(request: BackInStockNotificationRequest, itemDetails: BackInStockItemDetails): Promise<BackInStockNotificationRequest>
Notification request information.
Includes details for the out of stock item and the email address requesting to be notified when it's back in stock.
Item details to include in the notification when the item is back in stock.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a back in stock notification request.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteBackInStockNotificationRequest(_id: string): Promise<void>
ID of the notification request to delete.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a back in stock notification request.
Permission Scopes
For app development, you must have one of the following permission scopes:function getBackInStockNotificationRequest(_id: string): Promise<BackInStockNotificationRequest>
ID of the notification request to retrieve.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves the amount of back in stock requests for a given catalogReference
item.
Permission Scopes
For app development, you must have one of the following permission scopes:function getBackInStockNotificationRequestsCountByCatalogReferences(catalogReferences: Array<CatalogReference>): Promise<GetBackInStockNotificationRequestsCountByCatalogReferencesResponse>
catalogReference items to retrieve the notification request for.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Sets status
of a back in stock request to NOTIFICATION_SENT
.
Use this function if the notification is sent manually offline. If the notification is sent automatically or with the reportItemsBackInStock()
function, then status
updates on its own.
Permission Scopes
For app development, you must have one of the following permission scopes:function markAsNotificationSent(_id: string): Promise<MarkAsNotificationSentResponse>
ID of the notification request to mark.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a query to retrieve a list of back in stock notification requests.
The queryBackInStockNotificationRequests()
method builds a query to retrieve a list of back in stock notification requests and returns a RequestsQueryBuilder
object.
The returned object contains the query definition, which is typically used to run the query using the find()
method.
You can refine the query by chaining RequestsQueryBuilder
methods onto the query. RequestsQueryBuilder
methods enable you to sort, filter, and control the results that queryBackInStockNotificationRequests()
returns.
The following RequestsQueryBuilder
methods are supported for queryBackInStockNotificationRequests()
. For a full description of the Requests object, see the object returned for the items
property in RequestsQueryResult
."
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
_id | eq() ,ne() ,exists() ,in() ,hasSome() ,startsWith() ,ascending() ,descending() |
contactId | eq() ,ne() ,exists() ,in() ,hasSome() ,startsWith() ,ascending() ,descending() |
status | eq() ,ne() ,exists() ,in() ,hasSome() ,ascending() ,descending() |
autoNotified | eq() ,ne() ,exists() ,in() ,hasSome() ,ascending() ,descending() |
_createdDate | eq() ,ne() ,exists() ,in() ,hasSome() ,lt() ,le() ,gt() ,ge() ,ascending() ,descending() |
itemUrl | eq() ,ne() ,exists() ,in() ,hasSome() ,startsWith() ,ascending() ,descending() |
Permission Scopes
For app development, you must have one of the following permission scopes:function queryBackInStockNotificationRequests(): RequestsQueryBuilder
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Sends notifications for back in stock requests.
Important: Automations must be turned on in a site's dashboard for notifications to send.
This endpoint triggers notifications for requests in 1 of 2 ways:
- For a specific item, with the
catalogReference
information. - For specific requests, with
requestIds
.
itemDetails
are required and may populate dynamic values in the notification template, as follows:
itemDetails.name
passes to the template asitem.name
itemDetails.price
passes to the template asitem.price
itemDetails.image.url
passes to the template asitem.image.url
If the notification template doesn't include item.price
, item.name
, or item.image.url
, values should
be passed in extraAutomationTemplateParameters
.
After this endpoint is called, the status
for the request will update to NOTIFICATION_SENT
if it sends
successfully, or to FAILED
if it fails to send.
Permission Scopes
For app development, you must have one of the following permission scopes:function reportItemsBackInStock(itemDetails: BackInStockItemDetails, options: ReportItemsBackInStockOptions): Promise<void>
Item details to use in notifications.
itemDetails may populate dynamic valyes in the notification template, as follows:
- itemDetails.name passes to the template as item.name
- itemDetails.price passes to the template as item.price
- itemDetails.image.url passes to the template as item.image.url
Use extraAutomationTemplateParameters to pass additional dynamic values.
Report options.