Rule Product Alerts

Overview ¶

Summary ¶

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:

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.

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
        },
        { ... }
    ]
}

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

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.

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 ¶

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

{
    "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
}

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 ¶

Content-Type: application/json

{
  "email": "john@doe.com",
  "product_id": "ABCD1234",
  "tags": [
    "Newsletter"
  ]
}

Content-Type: application/json

{
  "message": "success"
}

Content-Type: application/json

{
  "error": "BadRequest",
  "message": "Subscriber email or phone_number not provided in request."
}

Content-Type: application/json

{
  "error": "BadRequest",
  "message": "Product_id not provided in request."
}

Content-Type: application/json

{
  "error": "UnexpectedError",
  "message": "An unexpected error occurred. Contact support if the error persists."
}

Content-Type: application/json

{
  "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
    }
  ],
  "pagination": {
    "prev": "/example-data?page[before]=yyy&page[size]=50",
    "next": "/example-data?page[after]=zzz&page[size]=50"
  }
}

Content-Type: application/json

{
  "product_id": "ABCD1234-56",
  "fields": [
    {
      "key": "color",
      "value": "blue"
    }
  ],
  "alert_tags": [
    "Custom Alert Triggered"
  ],
  "stock": 100
}

Content-Type: application/json

{
  "message": "success"
}

Content-Type: application/json

{
  "error": "ProductNotFound",
  "message": "No product matches with provided identifiers."
}

Content-Type: application/json

{
  "product_id": "ABCD1234-56"
}

Content-Type: application/json

{
  "message": "success"
}

Content-Type: application/json

{
  "error": "ProductNotFound",
  "message": "No product matches with provided product_id."
}

Content-Type: application/json

{
  "alert_settings": {
    "alert_min_stock": 10,
    "alerts_per_stock": 20,
    "updated_at": "2021-05-07 09:26:04.000"
  }
}

Content-Type: application/json

{
    "alert_min_stock" = 10,
    "alerts_per_stock" = 20
}

Content-Type: application/json

{
  "message": "success"
}