Skip to main content

Subscription CRUD

Subscription API payloads use camelCase. Server-managed fields are returned in responses but rejected in write requests.

Operation semantics

For AI integrations, list subscriptions before updating or deleting unless the user already supplied a subscription UUID. Write operations require an API key with the write scope; read-only keys receive 403 insufficient_scope.

Pagination

GET /api/v1/subscriptions returns results newest first by default and accepts two optional query parameters: The response includes a pagination object. Fetch the next page with offset + limit while hasMore is true.
Out-of-range values return 400 invalid_pagination.

Filtering, sorting, and automatic renewal rollover

GET /api/v1/subscriptions accepts optional filters and a sort order alongside pagination:
[!NOTE] Dynamic renewal rollover: Both GET /api/v1/subscriptions and GET /api/v1/subscriptions/{id} automatically advance overdue active non-trial subscriptions forward by whole billing periods to the next upcoming cycle (matching the web dashboard and Bark push reminders), including before evaluating expiringBefore and sort=nextPaymentDate. Free trials (isTrial: true) and paused / cancelled records are never rolled forward automatically.
Combine status=active with expiringBefore to answer “what renews soon”. Invalid values return 400 invalid_query with a field and suggestedFix.
The response echoes the applied query so an agent can confirm what produced the result:

Subscription object

When isTrial is true, the object also includes "trialEndsOn": "YYYY-MM-DD". When period is "custom", it includes "customDate": "<days>".

Writable fields

The server manages id, status (web-managed lifecycle state), createdAt, and updatedAt. Do not send server-managed fields in POST or PATCH requests (sending status or id returns 400 invalid_subscription_field).

Field rules

nextPaymentDate is the authoritative schedule date. For monthly billing, billingAnchorDay preserves the original calendar day across short months: January 31 → February 28/29 → March 31. If a charge repeats every 30 days rather than on a fixed day of each month, use period: "custom" with customDate: "30".

Free trials

To track a free trial before its first paid charge, set isTrial: true and trialEndsOn (plus nextPaymentDate set to the same date):
Free trials are one-shot deadlines: once trialEndsOn passes, SteadyRenew keeps the expired date visible instead of rolling it forward until you convert ({"isTrial": false, "nextPaymentDate": "2026-08-10"}) or delete the record.

Status vs delete

Responses include a read-only status (active, paused, or cancelled), and list queries may filter by it. The public API does not cancel, pause, or resume subscriptions by writing status, nor does it cancel billing with external providers. Calling DELETE /api/v1/subscriptions/{id} permanently removes the tracked subscription row from your ledger and records a subscription.delete entry (including a metadata.before snapshot) in the audit log. Only active subscriptions count toward active spend in the analytics endpoints.

Natural language examples

Add a subscription

User intent:
API call:

Change billing period

User intent:
Agent flow:
  1. Call GET /api/v1/subscriptions to identify the Netflix record.
  2. Ask the user to confirm the exact record and change.
  3. Call PATCH /api/v1/subscriptions/{id}.

Remove a duplicate

User intent:
Agent flow:
  1. Call GET /api/v1/subscriptions and find duplicate candidates.
  2. Ask the user to confirm the exact subscription name and id.
  3. Call DELETE /api/v1/subscriptions/{id}.

Custom billing period

For non-monthly/non-yearly intervals, set period to custom and send customDate as a positive whole-number string of days.
For a fixed 30-day interval, set customDate to "30"; do not use monthly. When patching from custom back to monthly or yearly, omit customDate; the server clears stale custom billing data automatically.

AI tool schema

Use ai-tools.json for tool/function definitions, risk levels, and confirmation prompts.