> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Operate Existing Subscriptions
> Change the commercial terms, timing, and end state of a subscription that already exists.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
Subscription operations are available under **Sales → Subscriptions** and through [Change Subscription](/api-reference/subscriptions/update). The Customer Portal exposes only the actions allowed by your [portal configuration](/features/customer-portal/settings).
## Change the plan
A plan change points the subscription at another recurring catalog item. Before sending it, check four boundaries:
1. **Currency must match.** The destination item must support the currency already locked to the subscription.
2. **Cancellation must be cleared.** A canceled or pending-cancellation subscription cannot change plan until it is uncanceled.
3. **Custom prices are excluded.** Pay-what-you-want items cannot be selected as the destination.
4. **Seat conversion is one-way.** A non-seat subscription may become seat-based; a seat-based subscription cannot become non-seat. The billing customer becomes a `team` customer and claims a seat during that conversion.
The selected [proration behavior](/features/subscriptions/proration) decides timing. `invoice` and `prorate` change the product now; `next_period` schedules it for renewal. A non-seat to seat conversion must happen immediately.
If the subscription is trialing, the trial start remains anchored to its original date while the end is recalculated from the destination item. A destination with no usable trial ends the trial and opens a paid billing period immediately.
```bash Change product theme={"system"}
curl --request PATCH \
--url https://api.getruba.com/v1/subscriptions/{subscription_id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"product_id": "",
"proration_behavior": "prorate"
}'
```
## Change the number of seats
For a [member-priced subscription](/features/seat-based-pricing), send the quantity the customer should pay for. `invoice` and `prorate` apply it immediately; `next_period` leaves the current quantity in place until renewal.
```bash Change seat quantity theme={"system"}
curl --request PATCH \
--url https://api.getruba.com/v1/subscriptions/{subscription_id} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{ "seats": 25, "proration_behavior": "invoice" }'
```
## Apply or change a discount
Set `discount_id` to attach another [discount](/features/discounts), or send `null` to remove the current one. The new discount state begins with the next billing cycle; Ruba does not recalculate the period already underway.
```json Subscription update theme={"system"}
{ "discount_id": "" }
```
## Manage the trial
The `trial_end` field controls both extension and conversion:
* Send a future timestamp to add or extend trialing access. An active subscription moves to `trialing`, and its next payment waits for that timestamp.
* Send `"now"` to close the trial. The subscription becomes active and begins a new paid billing period immediately.
```json Trial update theme={"system"}
{ "trial_end": "2026-06-01T00:00:00Z" }
```
## Reschedule the next renewal
Set `current_billing_period_end` to a future timestamp when the current paid period should run longer or renew on another date. Canceled subscriptions cannot be rescheduled.
```json Billing-period update theme={"system"}
{ "current_billing_period_end": "2026-07-15T00:00:00Z" }
```
## Cancel or revoke
Ruba separates stopping the next renewal from stopping access now.
### Keep access through the paid term
Set `cancel_at_period_end` to `true`. Ruba records the pending cancellation, generates no order after the current period, and leaves benefits active until `current_period_end`.
```json Period-end cancellation theme={"system"}
{
"cancel_at_period_end": true,
"customer_cancellation_reason": "too_expensive"
}
```
You may also store a customer-provided comment. The accepted reason values are `too_expensive`, `missing_features`, `switched_service`, `unused`, `customer_service`, `low_quality`, `too_complex`, and `other`.
A cancellation comment is visible in the customer’s purchase history. Store
only words the customer actually supplied, never internal support notes.
### Remove access immediately
Delete the subscription to revoke it. Ruba changes its state to `canceled`, records `ended_at`, and revokes benefits immediately. Revocation does not issue a refund; use the [refund flow](/features/refunds) separately when money should also be returned.
```bash Immediate revocation theme={"system"}
curl --request DELETE \
--url https://api.getruba.com/v1/subscriptions/{subscription_id} \
--header 'Authorization: Bearer '
```
This action cannot be undone.
### Resume a pending cancellation
Before the paid term ends, send `cancel_at_period_end: false`. Ruba clears the cancellation timestamps and returns the subscription to normal renewal. An already-ended subscription cannot be resumed.
## What customers can do
| Portal action | Availability |
| ---------------------------------- | ----------------------------------------------------------- |
| Cancel at period end | Always available. |
| Replace the default payment method | Always available. |
| Change plan | Available when plan changes are enabled in portal settings. |
| Change seat quantity | Available when seat management is enabled. |
Immediate revocation, discount changes, trial editing, and renewal rescheduling remain merchant-only operations.