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 to true. Use startCollectingRequests() in BackInStockSettings 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.

Was this helpful?

Yes

Setup

To use the BackInStockNotifications API, install the @wix/ecom package using npm or Yarn:

Copy

1npm install @wix/ecom

Copy

1yarn add @wix/ecom

Then import { backInStockNotifications } from @wix/ecom:

Copy

1import { backInStockNotifications } from '@wix/ecom'

Was this helpful?

Yes

createBackInStockNotificationRequest( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function createBackInStockNotificationRequest(request: BackInStockNotificationRequest, itemDetails: BackInStockItemDetails): Promise<BackInStockNotificationRequest>

Method Parameters

requestBackInStockNotificationRequestRequired

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.

itemDetailsBackInStockItemDetailsRequired

Item details to include in the notification when the item is back in stock.

Returns

Return Type:Promise<BackInStockNotificationRequest>

Was this helpful?

Yes

deleteBackInStockNotificationRequest( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function deleteBackInStockNotificationRequest(_id: string): Promise<void>

Method Parameters

_idstringRequired

ID of the notification request to delete.

Was this helpful?

Yes

getBackInStockNotificationRequest( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function getBackInStockNotificationRequest(_id: string): Promise<BackInStockNotificationRequest>

Method Parameters

_idstringRequired

ID of the notification request to retrieve.

Returns

Return Type:Promise<BackInStockNotificationRequest>

Was this helpful?

Yes

getBackInStockNotificationRequestsCountByCatalogReferences( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function getBackInStockNotificationRequestsCountByCatalogReferences(catalogReferences: Array<CatalogReference>): Promise<GetBackInStockNotificationRequestsCountByCatalogReferencesResponse>

Method Parameters

catalogReferencesArray<CatalogReference>Required

catalogReference items to retrieve the notification request for.

Returns

Return Type:Promise<GetBackInStockNotificationRequestsCountByCatalogReferencesResponse>

Was this helpful?

Yes

markAsNotificationSent( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function markAsNotificationSent(_id: string): Promise<MarkAsNotificationSentResponse>

Method Parameters

_idstringRequired

ID of the notification request to mark.

Returns

Return Type:Promise<MarkAsNotificationSentResponse>

Was this helpful?

Yes

queryBackInStockNotificationRequests( )

Developer Preview

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:

Learn more about permission scopes.

Copy

function queryBackInStockNotificationRequests(): RequestsQueryBuilder

Request

This method does not take any parameters

Returns

Return Type:RequestsQueryBuilder

Was this helpful?

Yes

reportItemsBackInStock( )

Developer Preview

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 as item.name
itemDetails.price passes to the template as item.price
itemDetails.image.url passes to the template as item.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:

Learn more about permission scopes.

Copy

function reportItemsBackInStock(itemDetails: BackInStockItemDetails, options: ReportItemsBackInStockOptions): Promise<void>

Method Parameters

itemDetailsBackInStockItemDetailsRequired

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.

optionsReportItemsBackInStockOptions

Report options.

Was this helpful?

Yes