---
title: "List recurring charges"
method: GET
path: "/v1/recurring_charges"
tags: ["Recurring charge"]
---

# List recurring charges

`GET /v1/recurring_charges`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/recurring_charges`
- Auth: HTTP bearer

Returns a paginated list of the company's recurring charges (subscription-like expected
charges), each including its `merchant` and `vendor_card` summaries and computed fields
(`finalized?`, `days_since_expected`, `overdue?`, `amount`). Sorting by the virtual field
`next_expected_at` is supported. Non-admin callers see charges they own, charges on their
cards, or all company charges if they hold `card_transactions_manage`.

## Query parameters

- `_start` integer
- `_end` integer
- `_order` 'asc' | 'desc'
- `_field` string
- `active` boolean
- `merchant_id` string, uuid
- `vendor_card_id` string

## Headers

- `company-id` string, uuid, required

## Response `200`

Paginated list of recurring charges

- RecurringCharge[]
  - `id` string, uuid, required
  - `company_id` string, uuid, required
  - `user_id` string, nullable: The owning user (defaults to the current user on creation).
  - `merchant_id` string, uuid, nullable
  - `vendor_card_id` string, nullable: The card expected to be charged.
  - `amount_cents` integer, required: Expected charge amount in cents.
  - `amount` object: The expected amount serialized as a Money object (via the app's `Money#to_hash` override).
    - `amount` string: Decimal amount as a string.
    - `formatted` string: Currency-formatted amount.
    - `cents` string: Amount in cents. Serialized as a string: Money runs with `default_infinite_precision`, so `cents` is a `BigDecimal` rendered as a JSON string. For an exponent-0 currency (e.g. CLP) this equals `amount`.
    - `currency_iso` string: ISO 4217 currency code.
  - `currency` string, required
  - `frequency` 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'semiannual' | 'annual', required
  - `source` 'manual' | 'auto_detected'
  - `start_date` string, date, required
  - `end_date` string, date, nullable
  - `next_expected_at` string, date, nullable: Next date a charge is expected.
  - `active` boolean
  - `description` string, nullable
  - `confidence_score` string, nullable: Detection confidence (0-100), for auto-detected charges.
  - `last_matched_at` string, date-time, nullable
  - `supporting_transaction_ids` string[]: Ids of the card transactions that support / were matched to this recurring charge (jsonb array; defaults to an empty array).
  - `finalized` boolean: Whether the charge has ended. Serialized in JSON as `finalized?`.
  - `overdue` boolean: Whether the next expected charge is overdue. Serialized in JSON as `overdue?`.
  - `days_since_expected` integer, nullable: Days elapsed since the charge was last expected.
  - `merchant` object, nullable
    - `id` string, uuid
    - `name` string
    - `image_url` string, nullable
  - `vendor_card` object, nullable
    - `id` string
    - `name` string
    - `last4` string
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad Request — the query used an unknown filter field or malformed filter DSL.
- `401`: Unauthorized
- `404`: The `company-id` header is missing or the caller is not a member of the company

---

[API](https://skmtc.dev/cardda/apis/accounting-api.md) - [All operations](https://skmtc.dev/cardda/apis/accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/accounting-api/revisions/49cf78d0f7ab?raw)