> ## 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.
# Choose How Plan Changes Settle
> Control when a price change takes effect and where its charge or credit appears.
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;
};
When price or seat quantity changes inside a paid period, part of the old term remains unused. Proration determines both the effective time of the new terms and how Ruba settles that unused value.
## Proration behaviors
| Value | New terms begin | Difference is settled |
| ------------- | -------------------------- | ------------------------------------------ |
| `invoice` | Immediately | On a new invoice now |
| `prorate` | Immediately | On the next scheduled invoice |
| `next_period` | At the next billing period | No mid-period charge or credit |
| `reset` | Immediately | Full new price now; billing cycle restarts |
### Invoice now: `invoice`
Ruba calculates the unused old value and the remaining-period value of the new plan, then invoices their difference immediately. An upgrade produces a charge; a downgrade produces a credit.
### Carry the difference: `prorate`
Access changes now, while the adjustment waits for the normal renewal invoice. If the billing interval itself changes, Ruba promotes this behavior to `invoice` because the old cycle no longer has a compatible next invoice.
For both immediate behaviors, a required immediate payment must succeed before Ruba commits the subscription change.
### Keep this period unchanged: `next_period`
Ruba stores the requested values in `pending_update`. Current access and billing remain unchanged until renewal, when the pending update replaces the current terms. A later immediate update supersedes and removes the pending one.
### Restart the cycle: `reset`
Ruba applies the new plan, charges its full price, and starts a fresh period at the change timestamp. No unused-value credit is created. `reset` is a preview behavior available on paid plans.
## Setting the default behavior
Choose the organization default under **Settings → Subscriptions** or through [Change Organization](/api-reference/organizations/update). Portal plan changes use this value when no operation-specific override is supplied.
## Overriding per update
Send `proration_behavior` with a product or seat update to replace the default for that request.
```bash Immediate settlement 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": "invoice"
}'
```
## How the prorated amount is calculated
Ruba measures the exact seconds remaining. With `S` seconds left in a period of `T` seconds:
```text theme={"system"}
old credit = old price × S / T
new remainder = new price × S / T
settlement = new remainder − old credit
```
For a $5 to $20 upgrade after one day of a 30-day period, 2,505,600 of 2,592,000 seconds remain. The old credit is $4.83, the new remainder is $19.33, and the settlement is a $14.50 charge. Reversing those prices produces a $14.50 credit.
Because Ruba uses real seconds, the time of day and the actual 28-, 29-, 30-, or 31-day month affect the result.