# Customer subscriptions

> Set up a customer’s payment schedule from a catalog service, then change or cancel it, knowing what happens to the payments it already created.

> **Note — For assistants**
>
> An assistant connected to the Qualy MCP server reads this guide as the resource `qualy://guides/subscriptions`. Generated from the Qualy MCP server’s guide registry.

A subscription is a customer's payment schedule: Qualy creates their payments from it, one each cycle. It is not your account's own Qualy plan, which the `billing_*` tools read.

## 1. Find the contact and the service

- The contact: `subscription_create` takes the payer's id or email, found as for a one-off payment ([`qualy://guides/payments`](/docs/mcp-server/guides/payments.md)).
- The service: each subscription bills a service from your account's catalog. `service_list` lists them by name (filter `status` active or archived); `service_get` takes an id or a name and shows its steps. `subscription_create` takes the service's id or name: an exact name (ignoring case) wins, otherwise a unique name prefix of 3 or more characters, and several matches come back as candidates to choose from.

## 2. Create it

`subscription_create` needs `name`, `contact`, `service`, `amount` (each payment, in major units), `currency`, `frequency` (every-week, every-2-weeks or every-month) and `startAt`, the first billing date (YYYY-MM-DD). The first payment falls due on `startAt`. After that, `dayOfMonth` (1 to 28) sets the day for an every-month plan, and `dayOfWeek` (0 = Sunday to 6 = Saturday) for an every-week one.

`mode` decides when it stops:

- `schedule` (the default, the dashboard's Scheduled): until `endAt`, the End date, and no payment falls due after it. Without `endAt` it runs until canceled.
- `amount-cap` (Amount cap): until the total of the payments it created reaches `endAmount`, which it requires. Each payment is the full amount, so the last one can take the total past `endAmount`.
- Don't create a `payment-intent-partial` (Partial payment) subscription here: that kind is set up from a payment's direct debit authorization, and one created here never creates or charges a payment.

Qualy creates the first payment on the start date (right away when that is today or earlier), then each next one once it falls due within 30 days.

The first call returns a preview to show the person: the amount and frequency, the due dates, how many payments and how much in all when it has an end, and when Qualy creates the first payment. It also says when a value you gave isn't used, such as `endAmount` on a Scheduled plan or `dayOfWeek` on an every-month one. It creates the subscription only when called again with their approval.

## 3. Change or cancel it

Find it with `subscription_list` (newest first; filter by `contact`, `status` or `mode`) and read it with `subscription_get`. The tools below take its id as `subscriptionId`.

`subscription_options` has one action, cancel. Its `available` is false once the subscription is Canceled or Expired, when nothing about it can be changed either. It says nothing about other changes: `subscription_update`'s preview checks each one.

- `subscription_update` changes the name, `description`, `amount`, `currency` or `settlementCurrency`. Payments Qualy creates from now on use the new details; the payments it already created keep what they ask, and the preview lists the ones still open. `description` replaces both texts (internal and external), so a text you leave out is cleared. Its schedule and billing (`frequency`, `dayOfMonth`, `dayOfWeek`, `startAt`, `endAt`, `endAmount`) are set when it is created and can't be changed afterwards, and a Canceled or Expired subscription can't be changed at all: the preview refuses both.
- `subscription_cancel` stops it: no further payments will be created. The payments it already created are not canceled and the customer can still pay them; the preview lists the open ones. Cancel those as payments (`payment_intent_cancel`, for a payment nothing has been paid on) if they shouldn't be paid. A Partial payment subscription's direct debit authorization is canceled with it. Refused for a subscription already Canceled or Expired.

Both preview first, and neither changes the payments the subscription already created.

## Worked examples

### List the services you can bill

```json
{
  "tool": "service_list",
  "arguments": {
    "status": "active"
  }
}
```

Pass the id it returns as service when you create the subscription.

### Bill a contact monthly until an End date

```json
{
  "tool": "subscription_create",
  "arguments": {
    "name": "Tuition 2027",
    "contact": "jane.doe@example.com",
    "service": "General English",
    "amount": 1200,
    "currency": "AUD",
    "frequency": "every-month",
    "dayOfMonth": 1,
    "startAt": "2027-02-01",
    "endAt": "2027-11-30"
  }
}
```

mode defaults to schedule. The preview lists the due dates, how many payments that is and the total.

Previews first: the call returns a preview to show the person. Call it again with the same arguments plus `confirmationId` and `userConfirmed: true` only after they approve.

### Check whether a subscription can still be canceled

```json
{
  "tool": "subscription_options",
  "arguments": {
    "subscriptionId": "66f2a9c41b7e3d0012a4c5e8"
  }
}
```

Cancel only when available is true. A change of name, amount or currency is checked by the subscription_update preview instead.

### Change the amount of future payments

```json
{
  "tool": "subscription_update",
  "arguments": {
    "subscriptionId": "66f2a9c41b7e3d0012a4c5e8",
    "amount": 1250
  }
}
```

Payments it already created keep their amount; the preview lists the ones still open.

Previews first: the call returns a preview to show the person. Call it again with the same arguments plus `confirmationId` and `userConfirmed: true` only after they approve.

### Cancel a subscription

```json
{
  "tool": "subscription_cancel",
  "arguments": {
    "subscriptionId": "66f2a9c41b7e3d0012a4c5e8"
  }
}
```

Tell the person which open payments the preview lists: they stay payable unless canceled as payments.

Previews first: the call returns a preview to show the person. Call it again with the same arguments plus `confirmationId` and `userConfirmed: true` only after they approve.