Subscriptions

agenta subscriptions is a read-and-cancel view onto everyone paying you on a recurring plan (created from a subscription payment link). It’s the fast path for support work: look up a subscriber, check their status, cancel on request.

agenta subscriptions list
agenta subscriptions cancel <id>

List subscriptions

agenta subscriptions list [--limit <n>] [--json]

number

default:"10"

Results per page, 1 to 100.

boolean

Output a single JSON object instead of a table.

Output

  Subscriptions (3 total)

  active     €19.99/month  jane@startup.io          253dbe6a-6b4d-4c40-a16f-aae31cfea271
  past_due   $49.00/month  ana@example.com          0fb760fa-bce8-48e6-a51a-d1c5c06075f5
  canceled   €199.00/year  team@bigco.eu            46d8d6cf-5281-4fed-b7c2-af1065b21ecc

  3 of 3 shown.

`--json`

{
  "total": 3,
  "hasMore": false,
  "items": [
    {
      "id": "253dbe6a-6b4d-4c40-a16f-aae31cfea271",
      "customerEmail": "jane@startup.io",
      "customerName": null,
      "planName": "Pro plan",
      "billingInterval": "month",
      "status": "active",
      "unitAmountMinor": 1999,
      "currency": "EUR",
      "currentPeriodEnd": "2026-09-06T00:00:00.000Z",
      "stripeSubscriptionId": "sub_1PQr..."
    }
  ]
}

The human table formats the amount for you (€19.99/month). In JSON, unitAmountMinor is an integer of the smallest currency unit (1999 = €19.99), the one exception to plain decimal amounts elsewhere in the API. Every other money field you’ll see (checkouts, invoices, payment links) is a plain decimal number.

Status values

Status	Meaning
`trialing`	In a free trial period.
`active`	Paying, current.
`past_due`	Latest charge failed, retrying.
`unpaid`	Retries exhausted, not yet cancelled.
`paused`	Billing paused.
`canceled`	Ended.
`incomplete`	First payment hasn’t completed yet.
`incomplete_expired`	First payment window expired before completing.

Cancel a subscription

agenta subscriptions cancel <id> [--now] [--json]

string

required

Subscription ID, e.g. 253dbe6a-6b4d-4c40-a16f-aae31cfea271.

boolean

default:"false"

Cancel immediately instead of at the end of the current billing period. Without this flag, the subscriber keeps access until their paid period ends and nothing is refunded.

boolean

Output a single JSON object instead of the human-readable summary.

agenta subscriptions cancel 253dbe6a-6b4d-4c40-a16f-aae31cfea271

--json

{
  "status": "active",
  "cancelAtPeriodEnd": true,
  "effectiveCancelDate": "2026-09-06",
  "currentPeriodEnd": "2026-09-06T00:00:00.000Z"
}

Cancel immediately:

agenta subscriptions cancel 253dbe6a-6b4d-4c40-a16f-aae31cfea271 --now

--json

{
  "status": "canceled",
  "cancelAtPeriodEnd": false,
  "effectiveCancelDate": "2026-08-06",
  "currentPeriodEnd": "2026-09-06T00:00:00.000Z"
}

Default to the no-flag form. --now skips the grace period the subscriber already paid for, so reach for it only when that’s actually the ask (fraud, duplicate signup, an explicit “cancel me right now”).

Change the plan (upgrade or downgrade)

agenta subscriptions change-plan <id> --to <linkId> [--dry-run] [--json]

string

required

Subscription ID.

string

required

The target product’s id (agenta products list). It must be a subscription product in the same currency and billing interval as the current plan, and a different one.

boolean

default:"false"

Print the quote and apply nothing.

One command, two API calls: the quote, then the change with the quote’s prorationDate echoed back, so what is charged is what was shown. Always look at the quote first:

agenta subscriptions change-plan 9811c905-1f61-459d-af03-18fb5aad47d8 --to 3f0c2d61-... --dry-run --json

--json

{
  "applied": false,
  "direction": "upgrade",
  "currency": "eur",
  "dueTodayMinor": 1234,
  "dueTodayVatMinor": 239,
  "effectiveAt": "2026-09-03T10:31:25.000Z",
  "nextInvoiceMinor": 4900,
  "nextInvoiceVatMinor": 1176,
  "nextInvoiceAt": "2026-10-03T10:45:13.000Z",
  "prorationDate": 1788434542
}

Then apply:

agenta subscriptions change-plan 9811c905-1f61-459d-af03-18fb5aad47d8 --to 3f0c2d61-... --json

--json

{
  "direction": "upgrade",
  "applied": true,
  "status": "active",
  "unitAmountMinor": 4900,
  "currency": "eur",
  "quote": { "...": "the quote above" }
}

Upgrade (the new plan costs more): the prorated difference is charged on the saved card now; dueTodayMinor says how much.
Downgrade (same or lower price): nothing today; the subscriber keeps the current plan until effectiveAt, the current period end, and agenta subscriptions list shows the scheduled switch as pendingPlanChange until then.
Cancel a scheduled downgrade: run the command again with --to set to the current plan’s id. The result says direction: "revert", nothing is charged, and pendingPlanChange is null again.
Money fields are integer minor units (4900 = €49.00). The subscription must be active or trialing.

Next steps

Customers

Look up who’s behind a subscription.

Invoices

Pull receipts for a paid billing cycle.

Subscriptions (SDK)

Manage subscriptions from your own backend.

Subscriptions (concept)

How subscription payment links and billing cycles work.

SDK

CLI

API Reference

List subscriptions

`--json`

Status values

Cancel a subscription

Change the plan (upgrade or downgrade)

Next steps

Customers

Invoices

Subscriptions (SDK)

Subscriptions (concept)

​List subscriptions

​--json

​Status values

​Cancel a subscription

​Change the plan (upgrade or downgrade)

​Next steps

Customers

Invoices

Subscriptions (SDK)

Subscriptions (concept)

List subscriptions

`--json`

Status values

Cancel a subscription

Change the plan (upgrade or downgrade)

Next steps