Subscriptions

agenta subscriptions is a read-and-cancel view onto everyone paying you on a recurring plan (created from a subscription product). Use it for support work: look up a subscriber, check their status, cancel on request.

agenta subscriptions list
agenta subscriptions cancel <id>
agenta subscriptions credit <id> -a <amount> --reason <text>

List subscriptions

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

number

default:"10"

Results per page, 1 to 100.

string

Only subscribers who typed this discount code.

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, fields whose name ends in Minor are integers in minor units (1999 = €19.99). Plain amount fields are decimals. See the money model.

Status values

Status	Meaning
`trialing`	In a free trial period.
`active`	Paying, current.
`past_due`	Latest charge failed, retrying.
`unpaid`	Retries exhausted, not yet canceled.
`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> [--json]

The cancellation takes effect at the end of the current period: the subscriber keeps access until their paid period ends, and nothing is refunded.

string

required

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

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"
}

Change the plan (upgrade or downgrade)

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

string

required

Subscription ID.

string

required

The ID of the target subscription product (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.

Give a credit

agenta subscriptions credit <id> -a <amount> --reason <text> [--json]

A credit takes money off the subscriber’s next invoice. The rules on when you can give one are on Subscriptions. You must be signed in (agenta login) as an owner or admin.

string

required

Subscription ID.

number

required

The credit in the plan’s currency, as a decimal (5.00).

string

required

Why you give it. The subscriber never sees it.

agenta subscriptions credit 9811c905-1f61-459d-af03-18fb5aad47d8 -a 10 --reason "Two days of downtime"

Output

€10.00 credited.
It comes off their next invoice on Oct 12, 2026, leaving €50.76 to pay.
They now hold €10.00 in unspent credit with you.

With --json, the result has amountMinor, currency, reason, creditBalanceMinor, nextInvoiceMinor, nextInvoiceDueAfterCreditMinor, nextInvoiceAt, createdBy, createdAt, and the idempotencyKey the command used. Each run is a new credit: running the command twice gives two credits.

List credits

agenta subscriptions credits <id> [--json]

Prints each credit given on the subscription (amount, reason, date) and the buyer’s unspent balance. With --json, the result is { items: [{ id, amountMinor, reason, createdBy, createdAt }], balanceMinor }.

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 products and billing cycles work.

SDK

CLI

API Reference

List subscriptions

`--json`

Status values

Cancel a subscription

Change the plan (upgrade or downgrade)

Give a credit

List credits

Next steps

Customers

Invoices

Subscriptions (SDK)

Subscriptions (concept)

​List subscriptions

​--json

​Status values

​Cancel a subscription

​Change the plan (upgrade or downgrade)

​Give a credit

​List credits

​Next steps

Customers

Invoices

Subscriptions (SDK)

Subscriptions (concept)

List subscriptions

`--json`

Status values

Cancel a subscription

Change the plan (upgrade or downgrade)

Give a credit

List credits

Next steps