Back to top

Rule Product Alerts [PRERELEASE]

This is the documentation for the Rule Product Alerts prerelease api. This documentation reflects pre-release software and may be subject to change at any time. If you find anything unclear or incorrect, or have any questions, please let us know by dropping an email to: integrations@rule.se

Overview

Summary

This documentation assumes that the reader has an active Rule account at https://app.rule.io and is familiar with the documentation at https://apidocs.rule.se.

Additional information about setting up marketing automations on the Rule platform can be found in Rule’s knowledge base article: Your First Marketing Automation

Product Alerts is a tool developed by Rule that integrates an inventory-tracking and alert system with the Rule platform.

Inventory levels are kept up to date through the Product Alerts API. As product stock is updated through the Product Alerts API, alerts are sent out to subscribers at a controlled rate that can be customized per-account through the API.

The Product Alerts API also supports custom tags (e.g. if the subscriber also signs up for a newsletter) and custom fields (for alert templates).

Alerts are triggered within the Rule platform with an account-managed automation.

The terminology and functionality has been kept as general as possible so that this feature can be used for multiple product alert scenarios. A few examples include:

  • Back-in-stock alerts to notify subscribers when a product is restocked

  • “Coming soon” notifications for new product launches

  • Product pre-order sign-ups to gauge interest in a product before a set production date

The graphic below details a typical flow for Product Alert:

flow diagram

Note

  • Products that have not been restocked in more than 365 days will automatically be deleted

  • All products are unique to the API key used to create the alert

Creating Alerts

The product alert flow starts with sending a Create Alert POST request. This will typically originate from a snippet on a webshop in which a subscriber signs up to be alerted when a product is in stock using their email or phone number.

When the request is sent, subscriber information is sent with with a unique product identifier (product_id).

Upon creation of an alert, the subscriber is also added to the account of the Rule platform. By default, the tag Rule - Waiting For Product Alert will be appended to the subscriber. A tag field can also be sent with the request to add any custom tags to the subscriber when the alert is first created (e.g. Newsletter).

The product identifier is used to identify a unique product. This should be a value that identifies the specific product that the subscriber is interested in, which may include product variation, size, and color. Depending on the inventory management system used, this could be just the product SKU, or a combination of fields.

Note When assigining a product_id to a product, be aware that different distribution regions will likely require separate groups of alerts for the same product. It is recommended to append the distribution region to the identifier used for product_id.

Updating Products

Product information is updated through the API through an Update product PUT call.

Every product update should include the unique product identifier (product_id) used to create the product (in the Create alert call). Products can only be updated if there is at least one subscriber waiting for an alert for a product.

This route is used to update the availability information of a product. The value used for the available stock should be directly reflected by the in stock/out of stock status on the product page. The value used in this parameter will overwrite the previous value, and is used to check if new alerts should triggered after every availability update.

This route can also be used to update the custom fields associated with the product. Custom fields are used to populate alert templates with product information (product name, product image URL, price, rating, etc.).

Alert tags can also be updated. This can be used when product alert automations need to be segmented, for example when segmenting “Back In Stock” alerts from “Coming Soon” alerts.

Getting Product Reports

Product reports can be generated to get a list of all the products that currently have pending alerts, along with the number of subscribers waiting for alerts.

Below is an example of a returned product report:

{
    "products": [
        {
            "product_id": "product_id_1",
            "custom_fields": "[]",
            "alert_tags": "[]",
            "created_at": "2021-05-04 12:02:51",
            "updated_at": "0000-00-00 00:00:00",
            "subscribers_waiting_for_alerts": 25
        },
        { ... }
    ]
}

Note

This request should also be used in combination with the Update Products route in order to retrieve a list of products that need updated inventory numbers to avoid unnecessary calls for products that don’t have any active alerts.

Triggering Alerts

Product alerts can only be triggered by updating the available stock quantities through the API.

A product alert is triggered on a single subscriber basis. Subscribers are notified in a chronological order from when they first subscribed to the alert.

Two parameters control when alerts are triggered: Minimum Stock and Alerts Per Stock Unit. These settings can be configured per API key through the Product Alert API.

Two conditions must be satisfied in order for an alert to be triggered:

  • Current Stock must be greater than Minimum Stock

  • Alerts Per Stock Unit * Current Stock must be less than the number of Sent Alerts

Example

You have 1000 subscribers waiting for a product alert. The current stock of the product is 0 units.

The inventory is updated through the Update Product route to 5 units. By default this doesn’t trigger any alerts to be sent, as the default alert_min_stock value is 10 units.

The inventory is then updated to 20 units. The default alert_per_stock value is 20, which will trigger alerts to be sent to 400 subscribers. These subscribers are removed from alerts for this product, leaving only 600 subscribers left waiting for a product alert.

The inventory is again updated to 100 units. This would trigger an additional 1,600 alerts (2,000 minus the original 400 already sent alerts). Alerts are sent to the remaining 600 subscribers and they are removed from alerts for this product. Since there are now no remaining subscribers, the product can now be considered “back in stock”. The product is then removed from the Product Alert database and will no longer show up in product reports.

When an alert is triggered for a subscriber, the subscriber’s tags are updated with any alert_tags that were set for the product. Any custom fields are also updated at this step so that automation templates are updated with information relevant to the product being triggered.

All custom fields set in the Product Alert API are applied to the custom group: Rule-ProductAlert in the Rule platform.

During a trigger, a default tag Rule - Product Alert Triggered is applied to the subscriber. A check is also performed to see if the subscriber is still subscribed to any other active product alerts. If not, then the default Rule - Waiting For Product Alert tag that was created when the alert was created is removed.

Example Use Cases

Product Launch Alerts

Multiple products launches are planned and you want a way to let customers know when each product launches in an automated way. Customers can be shown a sign-up form for the product that they want to be notified about on launch. When the form is submitted, a request is made to the Product Alert API to create a new alert.

Create Alert Request

{
    "email": "john@doe.com",
    "product_id": "ABCD1234-56-BLUE",
    "tags": ["Coming Soon Signup"]
}

The subscriber is added to the Rule platform and the tag Coming Soon Signup is applied to the subscriber which can be used to trigger an automation. The subscriber is also added to the new or existing product identified by the product_id.

When the product is launched, all subscribers can be alerted by updating the availability using the Update Product route, for example:

{
    "product_id": "ABCD1234-56-BLUE",
    "alert_tags": ["Product Launched"],
    "fields": [
        {
            "key": "name",
            "value": "Example Product 1"
        },{
            "key": "url",
            "value": "https://example.com/product1"
        },{
            "key": "color",
            "value": "Blue"
        },{
            "key": "size",
            "value": "56"
        }
    ],
    "stock": 1000
}

This API call sets the custom fields and tags to be applied for the product when a subscriber is alerted.

An automation can be triggered by the Product Launched tag, which would then assemble a product launch email template, which would use the custom field values that were applied during the Update Product route. In this example, the custom fields would be saved as:

  • Rule-ProductAlert.name = "Example Product 1"

  • Rule-ProductAlert.url = "https://example.com/product1"

  • Rule-ProductAlert.color = "Blue"

  • Rule-ProductAlert.size "56"

Authentication

To be able to use the API you must obtain an api key from your accounts settings page.

Once the api key has been generated it can be used in the following ways when making requests.

Passed as a get parameter:

apikey: YOUR-API-KEY-HERE

Passed as part of the request body:

apikey: YOUR-API-KEY-HERE

Passed as a header:

Authorization: Bearer YOUR-API-KEY-HERE

Failed authorization will result in a 401 response:

{
    "error": "NotAuthorized"
}

API

Run in Postman

Alerts

Create new alert
POST/alerts

An alert is created when a subscriber signs up to be notified of a product alert (such as a back in stock notification). Upon creation of an alert, a subscriber is added to the Rule platform. The subscriber is also added to the product that is specified by the identifier, product_id. If the product identifier is unique (i.e. no alerts have yet been created for the product), a new product will be created.

Attributes

  • product_id - (required) Unique product ID of product alert. This should be specific enough to specify any desired variations, color, size, and distribution region.

  • email - (required without phone_number)

  • phone_number - (required without email)

  • tags - (optional) A string array of tags that will be added to the subscriber on the Rule platform as soon as a new alert is created. By default, the tag Rule - Waiting For Product Alert will be automatically added to the subscriber when an alert is created.

  • language - (optional) Needs to be ISO 639-1 formatted. If no language is passed the subscriber will default to the account language.

  • fields - (optional) An array of data fields for the product. These fields will be saved to a subscriber when an alert is triggered, which can be used to template product-specific fields during a triggered automation. Note: If this attribute is provided it will overwrite any existing fields.

Example URI

POST https://ix.rule.io/productalert/alerts
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "john@doe.com",
  "product_id": "ABCD1234",
  "tags": [
    "Newsletter"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "success"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "BadRequest",
  "message": "Subscriber email or phone_number not provided in request."
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "BadRequest",
  "message": "Product_id not provided in request."
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "UnexpectedError",
  "message": "An unexpected error occurred. Contact support if the error persists."
}

Products

Get products
GET/products

Retrieve a list of products with pending alerts.

Example URI

GET https://ix.rule.io/productalert/products
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "products": [
    {
      "product_id": "ABCD1234-56",
      "custom_fields": [
        {
          "name": "product_name",
          "value": "Product 1",
          "type": "text"
        },
        {
          "name": "url",
          "value": "https://example.com/product-1",
          "type": "text"
        },
        {
          "name": "image_url",
          "value": "https://via.placeholder.com/150",
          "type": "text"
        }
      ],
      "alert_tags": [
        "Custom Alert Tag"
      ],
      "available_stock": 0,
      "sent_alerts": 0,
      "created_at": "2021-05-04 12:02:51",
      "updated_at": "0000-00-00 00:00:00",
      "subscribers_waiting_for_alerts": 240
    }
  ]
}

Update product
PUT/products

Updates existing products stored in the product alert database.

Attributes

  • product_id - (required) Unique product ID of product alert.

  • fields - (optional) An array of data fields for the product being updated. These fields will be saved to a subscriber when an alert is triggered, which can be used to template product-specific fields during a triggered automation. Note: If this attribute is provided it will overwrite any existing fields.

  • alert_tags - (optional) A string array of tags that are applied to a subscriber when an alert is triggered. Note: If this attribute is provided it will overwrite any existing alert tags.

  • stock - (optional) A numeric value of the current available stock units that are free to allocate.

Example URI

PUT https://ix.rule.io/productalert/products
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "product_id": "ABCD1234-56",
  "fields": [
    {
      "key": "color",
      "value": "blue"
    }
  ],
  "alert_tags": [
    "Custom Alert Triggered"
  ],
  "stock": 100
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "ProductNotFound",
  "message": "No product matches with provided identifiers."
}

Delete product
DELETE/products

Deletes a product entry and all pending alerts for that product.

Example URI

DELETE https://ix.rule.io/productalert/products
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "product_id": "ABCD1234-56"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "ProductNotFound",
  "message": "No product matches with provided product_id."
}

Settings

Get alert settings
GET/settings

Retrieve the current set of alert settings for the API key used to make the request.

Example URI

GET https://ix.rule.io/productalert/settings
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "alert_settings": {
    "alert_min_stock": 10,
    "alerts_per_stock": 20,
    "updated_at": "2021-05-07 09:26:04.000"
  }
}

Update alert settings
PUT/settings

Update the alert settings for alerts created by the API key. Alert settings affect when and how triggers occur based on product inventory.

Attributes

  • alert_min_stock - (optional) The minimum stock units needed to start triggering alerts. The default is 10.

  • alerts_per_stock - (optional) The number of alerts that are triggered for every inventory unit in stock. The default is 20.

Example URI

PUT https://ix.rule.io/productalert/settings
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "alert_min_stock" = 10,
    "alerts_per_stock" = 20
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "success"
}

Generated by aglio on 30 May 2022