Create Alert Request

Our app provides a JS widget that is compatible with Cornerstone and themes that have similar markup. With incompatible themes, there will be some development work required in order to be able to show the back-in-stock alerts form on the product detail page when an item or variant is out of stock.

One approach is to implement the frontend component yourself and send alert requests directly to our storefront API.

Create Alert Request

Endpoint

POST https://backinstockalerts.space48apps.com/api/${store_hash}/alert-requests

Path Parameters

Field	Type	Description
`store_hash`	string	Your BigCommerce store identifier. Typically found in the URL of your BigCommerce admin panel (e.g. `store-abc123` ).

Headers

Header	Value	Description
`Accept`	`application/json`	Required header to receive a JSON response.

Request Body

Field	Type	Description
`first_name`	string (optional)	Customer's first name.
`last_name`	string (optional)	Customer's last name.
`email`	string (required)	Customer’s email address.
`newsletter`	boolean (required)	Whether the customer opted into the newsletter.
`channel_id`	number (required)	BigCommerce channel ID.
`customer_id`	number or null (required)	BigCommerce customer ID, or `null` for guest users.
`currency_id`	number or null (required)	BigCommerce currency ID for the storefront.
`product_id`	number or string (required)	Product ID the customer wants to subscribe to.
`product_variant_id`	number or string or null (required)	Specific variant ID, or `null` for base product alerts.

🧪 Example Request

{
  "first_name": "Tom",
  "last_name": "",
  "email": "[email protected]",
  "newsletter": true,
  "product_id": "103",
  "channel_id": 1,
  "customer_id": null,
  "currency_id": 1,
  "product_variant_id": "CLC-LA"
}

Successful Response (200 OK)

Field	Type	Description
`data`	object	Created alert request object.
`data.id`	number	Unique identifier of the alert request.
`data.channel_id`	number	Channel associated with the request.
`data.created_at`	string	Timestamp the request was created (UTC).
`data.customer`	object	Contains minimal customer info.
`data.customer.email`	string	Email address used for the alert.
`data.order_total`	string	Order total at the time of request (currency formatted).

✅ Example Success Response

{
  "data": {
    "id": 65,
    "channel_id": 1,
    "created_at": "2023-01-19 09:32:16",
    "customer": {
      "email": "[email protected]"
    },
    "order_total": "£0"
  }
}

Error Response (4XX)

Field	Type	Description
`message`	string	General error message.
`errors`	object	Field-level validation errors.
`errors.email`	array of strings (optional)	Errors related to `email` .
`errors.channel_id`	array of strings (optional)	Errors related to `channel_id` .
`errors.customer_id`	array of strings (optional)	Errors related to `customer_id` .
`errors.currency_id`	array of strings (optional)	Errors related to `currency_id` .
`errors.product_id`	array of strings (optional)	Errors related to `product_id` .
`errors.product_variant_id`	array of strings (optional)	Errors related to `product_variant_id` .
`errors.first_name`	array of strings (optional)	Errors related to `first_name` .
`errors.last_name`	array of strings (optional)	Errors related to `last_name` .
`errors.newsletter`	array of strings (optional)	Errors related to `newsletter` .

❌ Example Error Response

{
  "message": "You are already subscribed to alerts for this product.",
  "errors": {
    "email": [
      "You are already subscribed to alerts for this product."
    ]
  }
}