---
title: "Subscriptions"
description: "Recurring billing. Define recurring plans and track customer subscriptions with trial, active, past due and cancelled states, including the next invoice date."
canonical: "https://obop.dev/apps/subscriptions/"
lang: "en"
---

# Subscriptions

## What it is for

Define recurring plans and track customer subscriptions with trial, active, past due and cancelled states, including the next invoice date. It does not create invoices by itself.

## What the package does and does not do

Recurring plans and customer subscriptions with a trial, active, past due and cancelled flow. It records the next invoice date; it does not create invoices on its own.

## Models

### `subscriptions_plan`

A recurring offer customers can subscribe to

Read group: `subscriptions.user`. Write group: `subscriptions.manager`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `name` | text | `none` | no | `subscriptions.user` | in clear | Plan name, for example Team yearly |
| `code` | text | `none` | no | `subscriptions.user` | in clear | Short code of the plan |
| `interval` | select (monthly, quarterly, yearly) | `none` | no | `subscriptions.user` | in clear | How often the customer is billed: monthly, quarterly, yearly |
| `price` | money | `none` | no | `subscriptions.user` | in clear | Standard price per billing interval (minor currency units, e.g. cents) |
| `trial_days` | number | `none` | no | `subscriptions.user` | in clear | Length of the free trial in days |
| `active` | bool | `none` | no | `subscriptions.user` | in clear | Whether new customers can pick the plan |

### `subscriptions_subscription`

A customer's recurring subscription to a plan

Read group: `subscriptions.user`. Write group: `subscriptions.manager`.

| Field | Kind | Data class | Personal data | Group | Agents see | Description |
|---|---|---|---|---|---|---|
| `customer_id` | ref → party | `none` | no | `subscriptions.user` | in clear | The customer who subscribed |
| `plan_id` | ref → subscriptions_plan | `none` | no | `subscriptions.user` | in clear | The plan subscribed to |
| `started_on` | date | `none` | no | `subscriptions.user` | in clear | Date the subscription began (YYYY-MM-DD) |
| `trial_ends_on` | date | `none` | no | `subscriptions.user` | in clear | Date the free trial ends (YYYY-MM-DD) |
| `next_invoice_on` | date | `none` | no | `subscriptions.user` | in clear | Date the next invoice is due (YYYY-MM-DD) |
| `recurring_amount` | money | `none` | no | `subscriptions.user` | in clear | Amount billed each interval after discounts (minor currency units, e.g. cents) |
| `currency` | text | `none` | no | `subscriptions.user` | in clear | ISO 4217 currency code, for example EUR |
| `seats` | number | `none` | no | `subscriptions.user` | in clear | Number of licences or users covered |
| `cancel_reason` | longtext | `none` | no | `subscriptions.user` | in clear | Why the customer cancelled |
| `state` | select (trial, active, past_due, cancelled) | `none` | no | `subscriptions.user` | in clear | Subscription status: trial, active, past_due, cancelled |

## Workflows

### `subscriptions_subscription`

| Action | Moves | Who may run it | Approval |
|---|---|---|---|
| `subscriptions_subscription.activate` | state: trial → active | `subscriptions.manager` | no |
| `subscriptions_subscription.mark_past_due` | state: active → past_due | `subscriptions.manager` | no |
| `subscriptions_subscription.recover` | state: past_due → active | `subscriptions.manager` | no |
| `subscriptions_subscription.cancel_trial` | state: trial → cancelled | `subscriptions.manager` | yes |
| `subscriptions_subscription.cancel` | state: active → cancelled | `subscriptions.manager` | yes |
| `subscriptions_subscription.cancel_overdue` | state: past_due → cancelled | `subscriptions.manager` | yes |

## Permission groups

Groups used by this app:

- `subscriptions.manager`
- `subscriptions.user`

## Approval steps

Steps an agent can only propose:

- `subscriptions_subscription.cancel_trial`
- `subscriptions_subscription.cancel`
- `subscriptions_subscription.cancel_overdue`

## What agents can and cannot do

An agent can read, search, create and update records of this app, and run the actions that need no approval, within the permission groups of its token.

It can only propose these steps, and a person must approve them: `subscriptions_subscription.cancel_trial`, `subscriptions_subscription.cancel`, `subscriptions_subscription.cancel_overdue`, `subscriptions_plan.delete`, `subscriptions_subscription.delete`.

## Dependencies

- `base`

## Install

Install it from the Customize app (Marketplace), or from the command line:

```bash
obop modules install-from subscriptions
```

Needs a database and administrator rights.

## Build your own

[The module guide shows how apps like this one are written](/docs/reference/module-manifest/)