# Loyalty API (beta)

The Loyalty API is Monterosa's engine for building loyalty programmes, gamification systems, and fan engagement experiences. It provides a composable set of building blocks – campaigns, triggers, effects, metrics, segments, and ladders – that let you design sophisticated reward mechanics without writing custom logic.

### What you can build

The API is designed around a simple principle: **if this happens, then do that**. By combining triggers (the "if") with effects (the "then") inside campaigns, you can create anything from a simple badge-collection mechanic to a full multi-tier loyalty programme with streaks, levels, and dynamic audience segmentation.

Common use cases include:

* [**Points and rewards**](https://products.monterosa.co/mic/reference/services/core-concepts#metrics) – Earn currency for completing activities, spend it on rewards
* [**Streak mechanics**](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/deep-dives/streaks) – Track consecutive daily or weekly engagement (think Duolingo-style streaks)
* [**Tiered loyalty**](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/deep-dives/ladders) – user level progression based on accumulated activity
* [**Badge collection**](https://products.monterosa.co/mic/reference/services/core-concepts#products) – Award achievements for completing campaigns or hitting milestones
* [**Dynamic segmentation**](https://products.monterosa.co/mic/reference/services/core-concepts#segments) – Automatically group users based on behaviour, then target them differently
* [**Cross-platform engagement**](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/integrations) – Wire external events in and push notifications or webhook calls out

### How it works

Everything flows through [**campaigns**](https://products.monterosa.co/mic/reference/services/core-concepts#campaigns). A campaign has one or more **steps**, each wired to a **trigger**. When a trigger fires for a user, the step completes and its **effects** run. Effects are the actions: award a badge, increment a metric, send a push notification, call an external webhook, check in to a streak, and more.

```
User action → Trigger fires → Campaign step completes → Effects execute
```

This event-driven architecture means the API is reactive. You define the rules, and the system executes them automatically as users interact with your product.

### Two interfaces

The API exposes two distinct surfaces:

| Interface     | Base path             | Purpose                                                                                                                           |
| ------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Admin API** | `/api/loyalty/admin/` | Full CRUD for all entities. Create campaigns, define triggers, manage users. Requires admin credentials.                          |
| **User API**  | `/api/loyalty/me/`    | Read-only views for end users. Retrieve profile, campaigns, rewards, metrics, segments, and ladder progress. Requires a user JWT. |

The Admin API is what you use to set up and manage your loyalty programme. The User API is what your client application calls to show personalised content to each user.

### Environments

<table><thead><tr><th width="145">Environment</th><th width="453">Base URL</th><th>Purpose</th></tr></thead><tbody><tr><td>Development</td><td><code>https://{spaceSlug}.spaces-dev.monterosa.cloud</code></td><td>Testing and integration</td></tr><tr><td>Production</td><td><code>https://{spaceSlug}.spaces-eu.monterosa.cloud</code><br><code>https://{spaceSlug}.spaces-us.monterosa.cloud</code></td><td>Live traffic</td></tr></tbody></table>

Replace `{spaceSlug}` with your allocated space identifier. Contact your Monterosa account team if you don't have one.

### What's next

* [Core Concepts](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/core-concepts) – Understand the building blocks before you start building
* [Authentication](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/deep-dives/authentication) – Get your credentials and make your first request
* [Quickstart](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/quickstart) – Build a working loyalty mechanic in 10 minutes
* [API Reference](https://products.monterosa.co/mic/reference/services/loyalty-api-beta/api-reference) – Full endpoint documentation