Skip to main content

Subscriptions

A subscription is an entity you create that tells Flux to keep an eye on a defined set of product prices and to push a notification to an external system whenever those prices change. Instead of having you poll the API on a schedule, you register a subscription once and let Flux deliver the changes as they happen.

Each subscription describes three things:

  1. What to watch. A "cart", the country and currency, and optional customer, delivery and sales channel context that Flux should use when it calculates prices.
  2. Where to send updates. A destination - either an HTTP webhook or a RabbitMQ exchange.
  3. How to batch updates. A maximum number of products per outbound notification (maxProductsPerEvent).

Why subscriptions exist​

Prices in Flux are not static values stored on a product. They are the result of a calculation that takes into account base prices, price lists, discounts, the customer making the request, the country and currency they're shopping in, the delivery method, and the sales channel. That calculation can change for many reasons that do not involve anyone touching the product itself: a discount starts or ends, a price list is updated, a campaign is scheduled, a delivery rule is changed.

For systems that need to keep a copy of the price (search engine, caches, etc), polling for these changes is not very efficient. With subscriptions you tell Flux which contexts you care about, and Flux tells you when something inside those contexts has produced a different result than the last time it was calculated.

You will typically want multiple subscriptions to deal with different kinds of prices. Eg one subscription for the public list prices, one subscription for member-only prices, etc.

When a subscription receives a notification you will get product prices that are active right now, but also any future prices that Flux currently knows about. Which is any future discount, price or price list that will become active in the future.

You will also receive a new notification if a future discount is rescheduled even if it doesn't affect the current price of the products.

Creating a subscription​

You can create a subscription through the API or through the Flux UI. In most cases it's simpler through the UI since you'll need to create a condition for which products you want in the subscription.

Destinations​

A destination tells Flux how and where to deliver notifications. There are two kinds at the time of writing, but if you need a new destination type then please let us know.

Webhook destination​

A webhook destination POSTs JSON over HTTPS to a URL you control. Flux supports authentication in the webhook either through basic authentication or with a custom header.

RabbitMQ destination​

A RabbitMQ destination publishes the same JSON payload to a RabbitMQ exchange.

Notification payload​

Whichever destination you choose, the payload Flux sends is the same JSON document:

{
  "subscriptionKey": "storefront-se",
  "results": [
    {
      "productId": "…",
      "countryCode": "SE",
      "currencyCode": "SEK",
      "productPriceCents": 19900,
      "discountedProductPriceCents": 14900,
      "discountedCartPriceCents": 14900,
      "startsAtUtc": "2026-04-25T00:00:00Z",
      "endsAtUtc": "2026-05-02T00:00:00Z"
    }
  ]
}

The top-level subscriptionKey is the key you supplied at creation time, which lets the receiver decide what to do with the message without having to look anything up. results is a list of up to maxProductsPerEvent ProductPriceCalculation objects, each describing a product whose calculated price changed since the last run, together with the validity window of the new price. If a single recalculation produces more changes than fit in one batch, Flux emits multiple notifications.

Tips
  • Choose key carefully — it's how the receiving end identifies the subscription, and it is part of every payload.
  • Start with a small maxProductsPerEvent (say, 50–100). You can raise it later if your consumer can handle larger batches without timing out.
  • Keep webhook handlers fast and idempotent. Flux retries on failure, so a slow handler that occasionally times out will see the same message more than once.