Customer subscriptions

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).
• 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

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

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

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

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

{
  "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.