Subscriptions
Subscriptions are recurring billing relationships. They renew automatically according to their plan's interval until canceled.
For all fields and options, see the Subscriptions API reference. The OpenAPI spec is also available for tooling.
The Subscription resource
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier (subscription_…). |
customerId | string | The customer this subscription belongs to. |
subscriptionPlanId | string | The plan this subscription is based on. |
name | string | Display name. |
quantity | number | Number of units. |
status | string | active, created, trial, on_grace_period, paused, or canceled. |
interval / intervalCount | string / number | Billing cadence (e.g. month × 1). |
mandate | Mandate | null | Payment method on file: { method, maskedIdentifier }. null until one is bound. |
startedAt / endedAt / canceledAt | string | null | Lifecycle timestamps (ISO 8601). |
nextRenewalAt / renewedUntil | string | null | Renewal timestamps. |
testmode | boolean | Whether this is a test subscription. |
Retrieve a subscription
GET /v1/subscriptions/{subscriptionId}
const subscription = await vatly.subscriptions.get("subscription_abc123");
console.log(subscription.mandate?.maskedIdentifier);
List subscriptions
GET /v1/subscriptions
const page = await vatly.subscriptions.list({ limit: 25 });
for await (const sub of vatly.subscriptions.listAll()) {
// ...
}
Update a subscription
PATCH /v1/subscriptions/{subscriptionId}
Common attributes: quantity, subscriptionPlanId (plan change), prorate,
applyImmediately, trialUntil. Include at least one of subscriptionPlanId,
price, or quantity; trialUntil cannot be sent alone. See the
API reference for all options.
const subscription = await vatly.subscriptions.update("subscription_abc123", {
quantity: 2,
});
Cancel a subscription
DELETE /v1/subscriptions/{subscriptionId} (204: no return value)
await vatly.subscriptions.cancel("subscription_abc123"); // period end
await vatly.subscriptions.cancel("subscription_other", { immediately: true });
The default schedules cancellation at period end (with a grace period);
immediately: true cancels immediately. Listen for the
subscription.canceled_* webhooks to react.
Resume a subscription
POST /v1/subscriptions/{subscriptionId}/resume
Resume a subscription that was canceled with a grace period, while that grace period is still active.
const subscription = await vatly.subscriptions.resume("subscription_abc123");
Update billing details (hosted link)
POST /v1/subscriptions/{subscriptionId}/billing-update-link
Returns a hosted link where the customer can update their payment method (mandate) or billing address. Redirect the customer to it.
const link = await vatly.subscriptions.createBillingUpdateLink("subscription_abc123", {
redirectUrlSuccess: "https://yourapp.com/billing/updated",
redirectUrlCanceled: "https://yourapp.com/billing",
});
redirect(link.href);
When the mandate changes, Vatly emits a subscription.billing_updated webhook so
you can refresh the masked payment method shown to the customer.