Subscription CRUD

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

Operation semantics

Operation	Use when	Risk	Confirmation
`GET /api/v1/subscriptions`	Search, summarize, analyze, or identify subscriptions	Low	Not required
`GET /api/v1/subscriptions/{id}`	Fetch one known record by UUID	Low	Not required
`POST /api/v1/subscriptions`	Record a new subscription	Medium	Required for AI agents
`PATCH /api/v1/subscriptions/{id}`	Change writable fields	Medium	Required for AI agents
`DELETE /api/v1/subscriptions/{id}`	Permanently remove a tracked record	High	Required for AI agents

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 and accepts two optional query parameters:

Parameter	Default	Rule
`limit`	`50`	Page size, 1 to 100
`offset`	`0`	Number of records to skip from the start

The response includes a pagination object. Fetch the next page with offset + limit while hasMore is true.

{
  "data": [ /* ... */ ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false },
  "requestId": "request-..."
}

curl -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  "https://your-site.example/api/v1/subscriptions?limit=50&offset=50"

Out-of-range values return 400 invalid_pagination.

Filtering and sorting

GET /api/v1/subscriptions accepts optional filters and a sort order alongside pagination:

Parameter	Rule
`status`	One of `active`, `paused`, `cancelled`
`category`	Exact category match, e.g. `Streaming`
`period`	One of `monthly`, `yearly`, `custom`
`q`	Case-insensitive search over the subscription name
`expiringBefore`	`YYYY-MM-DD`; returns records whose `nextPaymentDate` is on or before this date
`sort`	One of `createdAt`, `-createdAt`, `nextPaymentDate`, `-nextPaymentDate`, `amount`, `-amount`, `name`, `-name` (default `-createdAt`; `-` prefix is descending)

Combine status=active with expiringBefore to answer “what renews soon”. Invalid values return 400 invalid_query with a field and suggestedFix.

curl -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  "https://your-site.example/api/v1/subscriptions?status=active&expiringBefore=2026-07-01&sort=nextPaymentDate"

The response echoes the applied query so an agent can confirm what produced the result:

{
  "data": [ /* ... */ ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false },
  "query": { "sort": "nextPaymentDate", "filters": { "status": "active", "expiringBefore": "2026-07-01" } },
  "requestId": "request-..."
}

Subscription object

{
  "id": "33333333-3333-4333-8333-333333333333",
  "name": "Netflix",
  "category": "Streaming",
  "amount": 15.99,
  "currency": "USD",
  "period": "monthly",
  "lastPaymentDate": "2026-06-01",
  "nextPaymentDate": "2026-07-01",
  "billingAnchorDay": 1,
  "notificationEnabled": true,
  "status": "active",
  "createdAt": "2026-06-16T00:00:00.000Z",
  "updatedAt": "2026-06-16T00:00:00.000Z"
}

Writable fields

{
  "name": "Netflix",
  "category": "Streaming",
  "amount": 15.99,
  "currency": "USD",
  "period": "monthly",
  "nextPaymentDate": "2026-07-01",
  "billingAnchorDay": 1,
  "customDate": null,
  "notificationEnabled": true,
  "status": "active"
}

The server manages:

id
createdAt
updatedAt

Do not send server-managed fields in POST or PATCH requests.

Field rules

Field	Rule
`name`	Required, 1-120 characters
`category`	Required, 1-80 characters
`amount`	Required number, 0 to 999999.99, max 2 decimals
`currency`	Required. One of `CNY`, `USD`, `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `HKD`, `SGD`
`period`	Required. One of `monthly`, `yearly`, `custom`
`nextPaymentDate`	Required upcoming renewal date in `YYYY-MM-DD` format
`billingAnchorDay`	Optional monthly calendar anchor from 1-31; normally inferred from `nextPaymentDate`
`lastPaymentDate`	Deprecated compatibility input; converted into `nextPaymentDate` when the latter is omitted
`customDate`	Required only when `period` is `custom`; positive whole-number string of days
`notificationEnabled`	Optional boolean, defaults to `true`

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". lastPaymentDate remains in responses as a derived compatibility field and should not be used for new integrations.

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. Use DELETE when the user wants the tracked record removed. Only active subscriptions count toward active spend in the analytics endpoints.

Natural language examples

Add a subscription

User intent:

Add ChatGPT Plus, 20 USD per month, next renewal on 2026-07-17.

API call:

curl -X POST \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ChatGPT Plus","category":"AI","amount":20,"currency":"USD","period":"monthly","nextPaymentDate":"2026-07-17","notificationEnabled":true}' \
  https://your-site.example/api/v1/subscriptions

Change billing period

User intent:

Change Netflix to yearly billing.

Agent flow:

Call GET /api/v1/subscriptions to identify the Netflix record.
Ask the user to confirm the exact record and change.
Call PATCH /api/v1/subscriptions/{id}.

curl -X PATCH \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"yearly"}' \
  https://your-site.example/api/v1/subscriptions/33333333-3333-4333-8333-333333333333

Remove a duplicate

User intent:

Delete the duplicate Netflix subscription.

Agent flow:

Call GET /api/v1/subscriptions and find duplicate candidates.
Ask the user to confirm the exact subscription name and id.
Call DELETE /api/v1/subscriptions/{id}.

curl -X DELETE \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  https://your-site.example/api/v1/subscriptions/33333333-3333-4333-8333-333333333333

Custom billing period

For non-monthly/non-yearly intervals, set period to custom and send customDate as a positive whole-number string of days.

{
  "name": "Domain renewal",
  "category": "Infrastructure",
  "amount": 12,
  "currency": "USD",
  "period": "custom",
  "nextPaymentDate": "2026-07-16",
  "customDate": "45"
}

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.

AI tool schema

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

​Subscription CRUD

​Operation semantics

​Pagination

​Filtering and sorting

​Subscription object

​Writable fields

​Field rules

​Status vs delete

​Natural language examples

​Add a subscription

​Change billing period

​Remove a duplicate

​Custom billing period

​AI tool schema

Subscription CRUD

Operation semantics

Pagination

Filtering and sorting

Subscription object

Writable fields

Field rules

Status vs delete

Natural language examples

Add a subscription

Change billing period

Remove a duplicate

Custom billing period

AI tool schema