Working with Recipes

Recipes are pre-built incentive program configurations you can install in one click. Each recipe creates a complete setup (programs, program groups, distributors, all with sensible defaults) so you don’t have to build anything from scratch. You pick a recipe that matches what you’re trying to do, adjust a few customizable fields like commission rate, and hand off to your Siren admin to confirm.

This page explains how recipes work, the different ways to install them, and how agencies use them as a configuration-as-code primitive for client deployments.

The one-click install

The most common path is the recipe library at /recipes. Browse the list, find one that matches your use case, and click Install. The recipe page will walk you through any customizable fields (usually things like commission rate, cookie window, or program name) and then hand you off to your Siren admin to confirm the installation. Once you confirm, the programs, groups, and distributors are created and ready to use.

This is the path the Quick Start guide recommends for new users, and it’s the path you should default to whenever a library recipe fits your situation. It’s faster than building from scratch and the defaults are battle-tested.

Recipes are JSON under the hood

Every recipe is a JSON document that describes what to create: the programs and their engagement triggers, the program groups and their sorters, the distributors and their metric configurations, and the relationships between them. The customizable fields you see on the install screen are declared in the recipe’s frontmatter and map to specific paths inside the JSON.

This matters because it means recipes are deterministic and shareable. The same recipe JSON applied to two different Siren installs produces the same setup on both. There’s no hidden state, no install-specific logic, no “it worked on my install” surprises. If you have the JSON, you can reproduce the configuration anywhere.

Importing a recipe from JSON

If someone shares a recipe JSON with you (a colleague, an agency, a forum post, an AI assistant), you don’t have to publish it to the library to install it. Paste the JSON directly into the Siren admin’s recipe import field and it installs exactly the same way as a library recipe. Customizable fields are still respected, defaults still apply, and the end result is identical.

This is the supported path for custom or private recipes. Anything you’d build in the library, you can also build as standalone JSON and share directly.

For agencies: version-controlling client setups

If you build incentive programs for multiple clients, treat recipes as configuration-as-code. Save the recipe JSON for each client setup in a git repo or a shared drive, one file per client or one per program shape. When you onboard a new client, paste the matching recipe into their Siren install. When a client’s setup changes, update the JSON in version control and re-apply.

The same recipe JSON works on any Siren install, so staging-to-production promotion is a copy-paste. Build the recipe on a staging install, confirm it works, then paste the same JSON into production. No migration scripts, no database exports, no manual re-entry. This is the closest thing Siren has to infrastructure-as-code for incentive programs, and it’s what makes recipes the strongest single tool in the product for anyone managing multiple installs.

You can also keep your recipe library internal. You don’t have to publish anything to Siren’s library to use recipes this way. The JSON paste import gives you a fully private workflow.

What recipes can’t do today

Recipes are powerful, but there are a few gaps worth knowing about before you build a workflow around them.

There’s no built-in way to export a running Siren install as a recipe JSON. If you’ve built a custom setup by hand and want to capture it as a recipe, you don’t have a one-click path. You either need to have built the setup from a recipe in the first place (so you already have the JSON), or you need to describe the setup to Beacon and ask for the matching recipe. This is a known gap, and exporting from a live install is on the roadmap.

Siren also only installs recipes from its own library of trusted sources. You can’t point Siren at your own hosted recipe URL and have it pull recipes from there. The workaround is the JSON paste import described above, which works for any recipe you can put on your clipboard.

Beacon as a recipe assistant

For migrations and custom setups, Beacon is Siren’s free AI assistant that knows the recipe format and can generate recipe JSON for you based on a plain-language description. If you’re moving from another platform and want a Siren setup that mirrors what you had, describe the old setup to Beacon and ask for the matching recipe. If you want a recipe shape that doesn’t exist in the library yet, describe what you want and paste the result into your install.

Beacon is also how you fill the export gap. If you have a running setup you want to capture, describe it to Beacon in enough detail and it can produce a recipe that recreates it. This isn’t as clean as a real export, but it’s the closest thing available today.

Where to go next

Browse the library at /recipes to see what’s available. For the full Beacon workflow, including how it handles migrations and custom recipes, see What is Beacon?.