Subscriptions (operations)

The admin subscription surface is for operators, not integrating apps. It does three things: it lets you trigger the recurring-billing sweeps on demand (the same ones the schedulers run), it gives you a cross-app read (search + detail) over every subscription your grants cover, and it lets you cancel, pause, or resume an individual subscription through the same ops engine the app API uses.

App-facing subscription creation and the customer-managed lifecycle live in the Subscriptions guide and the Catalog & subscriptions concept. This page is the operator's view.

All endpoints below are admin, session-authenticated — send your session token:

-H "Authorization: Bearer SESSION_TOKEN"

Every response uses the standard envelope: { "data": …, "meta": { "success", "message", "errorCode", "timestamp" }, "pagination": … }. The examples show just the data payload after the first one. See Responses & errors for the full shape.

The subscription lifecycle

A subscription moves through five states. A subscription created against a trial price starts TRIALING (no charge yet; the first invoice falls at trial end); without a trial it starts ACTIVE (billed from its start date). A TRIALING or ACTIVE subscription is entitling — see Entitlements.

Permissions and scope

Reads gate on subscription:read; writes gate on subscription:write. The two behave differently with respect to app scope.

Out-of-scope behaviour differs by verb. A read of a subscription outside your grants is indistinguishable from a missing one — GET /admin/subscriptions/{id} returns 404 so the dashboard never leaks that another app's subscription exists, and a search simply omits it. A write resolves the subscription's owning app first: a non-existent id is 404, while an id that exists but sits outside your grants is 403. Metrics for an app you are not scoped to returns all-zero counts, not an error. App scope (RBAC-4) is enforced inside each use case — see RBAC.

On-demand sweeps

The recurring-billing machinery runs on schedulers by default. These three POST endpoints fire the same use cases on demand — useful for testing, for catching up after downtime, or for an operator-driven run. Each returns a per-run tally and each is resilient: a single bad subscription is logged and skipped so it never aborts the rest of the run, and per-row pessimistic locking makes a concurrent sweep safe (a candidate that is no longer eligible under the lock is counted as skipped). The sweeps are not audited; cancel/pause/resume are.

Configuration

Each sweep has an enable flag, an interval, and a tuning knob. The interval and tuning values default as shown; override them with the env-mapped properties.

Behavioural rules these knobs drive:

• Billing bills every due TRIALING/ACTIVE cycle and matures any subscription whose at-period-end cancel has come due (it is canceled with no further invoice).
• Trial reminder fires on the exact lead day: it selects TRIALING subscriptions whose trialEndDate equals today + lead-days (not <=), and emits one subscription.trial_will_end notification each. Running once a day therefore notifies each subscription exactly once, with no "reminder sent" flag.
• Dunning cancels every subscription stuck PAST_DUE whose past_due_since is on or before now − grace-days (i.e. past the grace window). A subscription whose payment recovers before the grace window expires returns to ACTIVE and is never touched by this sweep.

Run a sweep

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/billing/run \
  -H "Authorization: Bearer SESSION_TOKEN"

{
  "data": { "candidates": 12, "billed": 9, "canceled": 2, "skipped": 1, "failed": 0 },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": null
}

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/trial-reminders \
  -H "Authorization: Bearer SESSION_TOKEN"

{ "candidates": 4, "notified": 4, "failed": 0 }

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/dunning/run \
  -H "Authorization: Bearer SESSION_TOKEN"

{ "candidates": 3, "canceled": 2, "skipped": 1, "failed": 0 }

Run-summary fields

BillingRunSummary — POST /admin/subscriptions/billing/run

TrialReminderRunSummary — POST /admin/subscriptions/trial-reminders

DunningCancelRunSummary — POST /admin/subscriptions/dunning/run

The subscription.trial_will_end event is delivered to the owning app like any other webhook — see Webhooks and Webhooks & logs.

Cross-app search and detail

GET /admin/subscriptions returns a paginated, filterable list of subscription summaries across every app your subscription:read grants cover (a Super Admin or holder of a global grant is unrestricted). Results are automatically narrowed to your scope.

Query parameters

curl -G http://localhost:8080/api/v1/admin/subscriptions \
  -H "Authorization: Bearer SESSION_TOKEN" \
  --data-urlencode "applicationId=42" \
  --data-urlencode "mode=LIVE" \
  --data-urlencode "status=PAST_DUE"

{
  "data": [
    {
      "id": 9007,
      "status": "PAST_DUE",
      "productId": 310,
      "priceId": 540,
      "startDate": "2026-01-15",
      "nextBillingDate": "2026-06-15",
      "cancelAtPeriodEnd": false,
      "mode": "LIVE",
      "createdAt": "2026-01-15T09:30:00Z"
    }
  ],
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

SubscriptionSummaryDto (list row)

Detail

GET /admin/subscriptions/{id} returns the full read model for one subscription, including the resolved external customerReference. A subscription outside your scope reads as 404, exactly like a missing id.

curl http://localhost:8080/api/v1/admin/subscriptions/9007 \
  -H "Authorization: Bearer SESSION_TOKEN"

{
  "id": 9007,
  "status": "PAST_DUE",
  "productId": 310,
  "priceId": 540,
  "customerReference": "cust_a1b2c3",
  "startDate": "2026-01-15",
  "currentPeriodStart": "2026-05-15",
  "nextBillingDate": "2026-06-15",
  "cancelAtPeriodEnd": false,
  "mode": "LIVE",
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-06-16T02:10:00Z"
}

SubscriptionDto (detail)

Cancel, pause, and resume

These three writes drive the same ops engine as the app API — there is no parallel admin path. Each resolves the subscription's owning app_id + mode cross-app, enforces the per-app subscription:write scope (403 if you lack it on that app), runs the op, and writes an append-only audit entry atomically with the change. A non-existent id is 404.

CancelSubscriptionRequest

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/9007/cancel \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "atPeriodEnd": true }'

{
  "id": 9007,
  "status": "PAST_DUE",
  "productId": 310,
  "priceId": 540,
  "customerReference": "cust_a1b2c3",
  "startDate": "2026-01-15",
  "currentPeriodStart": "2026-05-15",
  "nextBillingDate": "2026-06-15",
  "cancelAtPeriodEnd": true,
  "mode": "LIVE",
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-06-30T12:00:00Z"
}

With atPeriodEnd: true the subscription keeps its status and nextBillingDate but flips cancelAtPeriodEnd to true; the next billing sweep matures the cancel when the period ends. With atPeriodEnd: false the subscription transitions to CANCELED immediately. Pause and resume take no body:

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/9007/pause \
  -H "Authorization: Bearer SESSION_TOKEN"

curl -X POST http://localhost:8080/api/v1/admin/subscriptions/9007/resume \
  -H "Authorization: Bearer SESSION_TOKEN"

Both return the updated SubscriptionDto.

Metrics

GET /admin/subscriptions/metrics returns the per-app, mode-aware subscription counts for the dashboard metrics row. Both applicationId and mode are required query parameters.

curl -G http://localhost:8080/api/v1/admin/subscriptions/metrics \
  -H "Authorization: Bearer SESSION_TOKEN" \
  --data-urlencode "applicationId=42" \
  --data-urlencode "mode=LIVE" \
  --data-urlencode "from=2026-06-01" \
  --data-urlencode "to=2026-06-30"

{
  "totalCount": 128,
  "activeCount": 96,
  "trialingCount": 12,
  "pastDueCount": 7,
  "canceledCount": 13
}

SubscriptionMetricsDto

Related