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.
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: BothCombineGET /api/v1/subscriptionsandGET /api/v1/subscriptions/{id}automatically advance overdueactivenon-trial subscriptions forward by whole billing periods to the next upcoming cycle (matching the web dashboard and Bark push reminders), including before evaluatingexpiringBeforeandsort=nextPaymentDate. Free trials (isTrial: true) andpaused/cancelledrecords are never rolled forward automatically.
status=active with expiringBefore to answer “what renews soon”. Invalid values return 400 invalid_query with a field and suggestedFix.
Subscription object
isTrial is true, the object also includes "trialEndsOn": "YYYY-MM-DD". When period is "custom", it includes "customDate": "<days>".
Writable fields
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, setisTrial: true and trialEndsOn (plus nextPaymentDate set to the same date):
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-onlystatus (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:Change billing period
User intent:- Call
GET /api/v1/subscriptionsto identify the Netflix record. - Ask the user to confirm the exact record and change.
- Call
PATCH /api/v1/subscriptions/{id}.
Remove a duplicate
User intent:- Call
GET /api/v1/subscriptionsand find duplicate candidates. - Ask the user to confirm the exact subscription name and id.
- Call
DELETE /api/v1/subscriptions/{id}.
Custom billing period
For non-monthly/non-yearly intervals, setperiod to custom and send customDate as a positive whole-number string of days.
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.