Proration for Subscription Upgrades and Downgrades

When a customer switches plans mid-cycle, they’ve already paid for time they won’t use on the old plan — and they owe for time on the new one. Proration is how Macropay settles that difference fairly, down to the day. Because Macropay is the merchant of record, every prorated charge and credit is recalculated with the correct sales tax / VAT for the customer’s location, remitted on your behalf. You change the plan; we handle the tax math, the invoice line items, and the compliance.

How proration works in Macropay

Whichever proration type you pick, one thing is constant:

The plan switch is always immediate. The moment you update the subscription, the customer is on the new product — upgrade or downgrade. Proration only controls when the price difference is settled, never whether the change takes effect.

You have two settlement behaviors:

Proration type	Behavior	Settles the difference
`invoice`	Invoice immediately	A one-off charge (upgrade) or credit (downgrade) is issued right away.
`prorate`	Next invoice	The adjustment is rolled into the customer’s next regular invoice.

If the billing interval changes (for example daily → monthly, or monthly → yearly, or the reverse), proration is always settled immediately as invoice, even when your default is set to prorate.

Set the default behavior

Pick one default that applies to every plan change in your organization. You can override it per-request through the API (see below).

From the dashboard

Open Organization Settings

In the Macropay dashboard sidebar, click Settings, or go straight to:https://macropay.ai/dashboard/${org_slug}/settingsScroll to the Subscriptions section.

Select a proration type

Choose Invoice Immediately or Next invoice. The change saves on selection.

From the API

Prefer to manage settings programmatically? Update the organization default with the organization update endpoint.

Change a plan with proration via API

This is the per-subscription path: switch a customer’s product and decide, on the spot, how the difference settles.

Create an organization access token

Generate an OAT by following the organization access tokens guide.

Save the token

Copy the token as soon as it’s shown — it won’t be displayed again.

Find the subscription ID

In the sidebar, go to Sales › Subscriptions, or:https://macropay.ai/dashboard/${org_slug}/sales/subscriptions

Open the subscription you want to change and copy its Subscription ID.

Find the target product ID

Go to Products › Catalogue, or:https://macropay.ai/dashboard/${org_slug}/products

On the product you’re switching the customer to, open the ⋮ (More options) menu and choose Copy Product ID.

Call the Update Subscription endpoint

Send a PATCH to /v1/subscriptions/{id}. Replace:

<subscription_id> — the subscription being changed
<product_id> — the product to switch to
proration_behavior — invoice (settle now) or prorate (settle on next invoice)

curl --request PATCH \
  --url https://api.macropay.ai/v1/subscriptions/<subscription_id> \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "<product_id>",
    "proration_behavior": "invoice"
  }'

from macropay import Macropay

with Macropay(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as macropay:

    res = macropay.subscriptions.update(
        id="<subscription_id>",
        subscription_update={
            "product_id": "<product_id>",
            "proration_behavior": "invoice",  # or "prorate"
        },
    )

    print(res)

Building usage-based or agent billing on top of subscriptions? The same model applies. Pair a base plan with metered prices so customers can move tiers mid-cycle while you keep billing by usage, activity, or outcome — prorated automatically on the fixed portion.

Worked examples

To make the math concrete, set up a product with two plans — a $8/month Starter** and a **$ 24/month Pro — following create product variants. Assume a 30-day billing month and that the customer switches on day 16, with 15 days remaining. For a 31-day month, the same logic applies with the remaining-days count adjusted accordingly.

Upgrading the subscription

Walk through the merchant and customer experience in subscription upgrades. invoice — charge the difference now The unused Starter time is credited and the remaining Pro time is charged, netted into one immediate invoice.

prorate — charge the difference on the next invoice The same net amount is calculated, but it lands on the customer’s next regular invoice instead of being billed today.

Downgrading the subscription

Walk through the full flow in subscription downgrades. invoice — credit the difference now The unused Pro time is credited against the remaining Starter cost and applied immediately.

prorate — credit the difference on the next invoice The same credit is deferred and reflected on the next regular invoice.

Remember: any change that also changes the billing interval is settled immediately as invoice, regardless of your default or the proration_behavior you pass.

Getting Started

Guides

Proration for Subscription Upgrades and Downgrades

How proration works in Macropay