Create alert request

Use this endpoint when the built-in Stencil widget does not fit your theme or when you are building a headless storefront. Your storefront is responsible for collecting the customer's details and consent before sending the request.

Request

POST https://backinstockalerts.hypaapps.com/api/stores/{store_hash}/alert-requests
Accept: application/json

Path parameter	Type	Description
store_hash	string	BigCommerce store hash, such as abc123. It appears in BigCommerce admin URLs as store-abc123.

Body fields

Field	Type	Required	Description
first_name	string	No	Customer's first name.
last_name	string	No	Customer's last name.
email	string	Yes	Customer's email address.
newsletter	boolean	Yes	Whether the customer explicitly opted into newsletter marketing.
channel_id	number	Yes	BigCommerce storefront channel ID.
customer_id	number or null	Yes	Logged-in BigCommerce customer ID, or null for a guest.
currency_id	number or null	Yes	BigCommerce currency ID for the storefront.
product_id	number or string	Yes	Product the customer wants to follow.
product_variant_id	number, string or null	Yes	Selected variant ID, or null for a simple product.

For example:

{
  "first_name": "Sam",
  "last_name": "Taylor",
  "email": "sam@example.com",
  "newsletter": true,
  "channel_id": 1,
  "customer_id": null,
  "currency_id": 1,
  "product_id": 103,
  "product_variant_id": 204
}

Successful response

A successful request returns 200 OK with the created alert request.

Field	Type	Description
data.id	number	Alert-request ID.
data.channel_id	number	Channel associated with the request.
data.created_at	string	UTC creation timestamp.
data.customer.email	string	Email address used for the alert.
data.order_total	string	Currency-formatted order total recorded with the request.

{
  "data": {
    "id": 65,
    "channel_id": 1,
    "created_at": "2026-01-19 09:32:16",
    "customer": {
      "email": "sam@example.com"
    },
    "order_total": "£0"
  }
}

Validation errors

A 4xx response contains a general message and may contain field-level arrays in errors.

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

Validation errors can be returned for email, channel_id, customer_id, currency_id, product_id, product_variant_id, first_name, last_name and newsletter.

Troubleshoot redirects or CORS errors

Symptom: The browser reports a cross-origin error, or the request receives a 302 redirect to the store domain.

Likely cause: The request does not ask for a JSON response.

Resolution: Include this header exactly:

Accept: application/json