Subscription lifecycle

The lifecycle actions

Once a subscription is live, you manage it through lifecycle actions: change the plan (upgrade/downgrade, with a proration preview first), pause it, resume it, and eventually cancel it. Each SDK exposes these as subscription-level operations.

All proration amounts are integers in minor units. A plan change previews a net credit/charge before you commit it.

Construct a client

import { Recurso } from 'recurso';

const recurso = new Recurso('sk_live_your_api_key', {
  baseUrl: 'https://api.recurso.dev',
});

ctx := context.Background()
client := recurso.NewClient("sk_live_your_api_key")

from recurso import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.recurso.dev",
    token="sk_live_your_api_key",
)

Preview a plan change (proration)

Preview the proration for switching to a new plan before committing. Nothing is charged or persisted — you get back the credit for unused time, the charge for the new plan, the net, and whether it’s an upgrade.

previewChange was added to the Node SDK — make sure you’re on a release that includes it (published after v1.5.0). All three SDKs now expose the preview.

const preview = await recurso.subscriptions.previewChange(subscription.id, newPlan.id);

preview, err := client.Subscriptions.PreviewChange(ctx, subscription.ID, newPlan.ID)
if err != nil {
	log.Fatal(err)
}
log.Printf("net=%d total=%d upgrade=%t", preview.NetAmount, preview.TotalAmount, preview.IsUpgrade) // minor units

from recurso.api.subscriptions import preview_plan_change

preview = preview_plan_change.sync(
    id=subscription.id,
    client=client,
    plan_id=new_plan.id,
)

Apply the plan change

Committing the change updates the subscription to the new plan and prorates per the preview.

const updated = await recurso.subscriptions.update(subscription.id, {
  plan_id: newPlan.id,
});

updated, err := client.Subscriptions.Update(ctx, subscription.ID, &recurso.SubscriptionUpdateParams{
	PlanID: newPlan.ID,
})
if err != nil {
	log.Fatal(err)
}

from recurso.api.subscriptions import update_subscription
from recurso.models import UpdateSubscriptionBody

updated = update_subscription.sync(
    id=subscription.id,
    client=client,
    body=UpdateSubscriptionBody(plan_id=new_plan.id),
)

Pause the subscription

Pausing halts billing without cancelling. The subscription can be resumed later.

await recurso.subscriptions.pause(subscription.id);

_, err = client.Subscriptions.Pause(ctx, subscription.ID)
if err != nil {
	log.Fatal(err)
}

from recurso.api.subscriptions import pause_subscription

pause_subscription.sync(id=subscription.id, client=client)

Resume the subscription

Resume a paused subscription to restart billing on its schedule.

await recurso.subscriptions.resume(subscription.id);

_, err = client.Subscriptions.Resume(ctx, subscription.ID)
if err != nil {
	log.Fatal(err)
}

from recurso.api.subscriptions import resume_subscription

resume_subscription.sync(id=subscription.id, client=client)

Cancel the subscription

Cancellation defaults to period end (the customer keeps access until the current period closes). Pass immediately: true to cancel now. A reason is recorded; Python takes it as an enum.

await recurso.subscriptions.cancel(subscription.id, {
  reason: 'too_expensive',
  // immediately: true, // cancel now instead of at period end
});

immediately := true
result, err := client.Subscriptions.Cancel(ctx, subscription.ID, &recurso.SubscriptionCancelParams{
	Reason:      "too_expensive",
	Immediately: &immediately, // omit for cancel-at-period-end
})
if err != nil {
	log.Fatal(err)
}
log.Printf("status=%s", result.Status)

from recurso.api.subscriptions import cancel_subscription
from recurso.models import CancelSubscriptionRequest, CancelSubscriptionRequestReason

cancel_subscription.sync(
    id=subscription.id,
    client=client,
    body=CancelSubscriptionRequest(
        reason=CancelSubscriptionRequestReason.TOO_EXPENSIVE,
        immediately=True,  # omit for cancel-at-period-end
    ),
)

A canceled subscription can often be brought back with recurso.subscriptions.reactivate(id) (Node) / client.Subscriptions.Reactivate(ctx, id) (Go) / reactivate_subscription.sync(id=..., client=client) (Python), subject to its current status.

Get Started

By Language

Workflows

The lifecycle actions

​The lifecycle actions

​Related

The lifecycle actions

Related