---
title: "Confirm, rename, re-time, re-price, stop, or dismiss a recurring series."
method: POST
path: "/v1/recurring/update"
---

# Confirm, rename, re-time, re-price, stop, or dismiss a recurring series.

`POST /v1/recurring/update`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/recurring/update`
- Auth: HTTP bearer

Confirm, rename, re-time, re-price, stop, or dismiss a recurring series. Any field on a candidate confirms inclusion in the schedule, including a deliberately selected variable payment; several ids may share one status-only change. Initial curation should favor predictable bills and subscriptions. Preserve existing agent placements rather than resetting them to automatic defaults.

## Headers

- `Idempotency-Key` string, required

## Request body

- RecurringUpdateRequest: Confirm, rename, re-time, re-price, stop, or dismiss a series. Pass exactly one of recurring_item_id or recurring_item_ids; several ids may only share a status change.
  - `associate_from` string: Explicitly associate this unconfirmed candidate with recurring_item_id, the existing curated series. Links its observed identity to the target without merging or deleting evidence groups. Payments must still meet the approved date and amount bounds. Preserves the target schedule or dismissal. Read possible_matches as evidence before confirming; no similarity match applies automatically.
  - `recurring_item_id` string
  - `recurring_item_ids` string[]: Several series for one status-only change, such as confirming every candidate at once.
  - `status` 'active' | 'stopped' | 'dismissed': active confirms inclusion in the schedule; stopped records that a real series ended; dismissed excludes a false or unsuitable schedule detection from the default list. Candidates already contribute nothing to commitment totals. Stopping or dismissing preserves transactions and does not cancel a payment. Any other field on a candidate also confirms it unless an explicit status is supplied. Re-read effective state after changing it.
  - `merchant_name` string
  - `cadence` 'weekly' | 'biweekly' | 'semimonthly' | 'monthly' | 'quarterly' | 'semiannual' | 'annual': How often the series posts: weekly, biweekly, semimonthly, monthly, quarterly, semiannual, or annual.
  - `amount_min` string: Inclusive minimum payment as Money text. Supply with amount_max for a variable bill; the range must contain amount. No percentage tolerance is inferred.
  - `amount_max` string: Inclusive maximum payment as Money text. Supply with amount_min in the series currency. Supplying amount alone resets matching to that exact amount.
  - `amount` string: Money text in the series' own currency, such as "USD 13.00".
  - `category` string
  - `next_expected_date` string, date: Set the first date of the approved schedule. Later occurrences advance on this cadence even after early, late, or missed postings.
  - `ends_at` string, date, nullable: The date a finite series ends; null clears it.
  - `date_tolerance_days` integer
  - `approval_note` string: Why the series reads this way. Defaults to the action reason.
  - `approval_source` string
  - `set_by` string

## Response `200`

Envelope with each series as it now reads, plus next actions and any schedule warnings.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

[API](https://skmtc.dev/candor/apis/candor-api.md) · [All operations](https://skmtc.dev/candor/apis/candor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/candor/apis/candor-api/revisions/6c050f72e956?raw)