Cancellation

A cancel stops charging right away. There is no "cancel at period end" mode. A subscription can be cancelled two ways: by you through the API or dashboard, or by the payer from their own wallet.

Strimz never cancels on its own. A subscription that runs out of retries moves to lapsed, which is a separate status.

Cancelling from the API

await strimz.subscriptions.cancel({
  id: 'cmq4wck6a0002je6lfmb5bgjp',
  reason: 'customer request',
})

reason is optional and stored on the subscription for your own audit.

What happens during the call:

1. The row's status becomes cancelled and cancelledAt is set.
2. subscription.cancelled fires with data.status: 'cancelled'.
3. The scheduler stops picking the subscription up, so no more charges are taken.

Cancelling a subscription that is already cancelled or lapsed returns an error.

The API also queues an on-chain cancel() so the contract's state matches. The scheduler sends it with its charger key, and skips it if the subscription is already cancelled on chain. This works with the subscriptions contract from the next testnet redeploy (#142). On the current deployment the on-chain cancel still reverts, so the contract shows the subscription as live, although Strimz no longer charges it.

Cancelling from the payer's wallet

The contract's cancel(uint256 subscriptionId) can be called by the payer, by the merchant's registry owner, or by Strimz's scheduler acting on an API cancel. A payer can call it from any wallet tool that can send a contract call. The indexer sees the SubscriptionCancelled event and marks the row cancelled.

Strimz has no hosted cancel page for payers, and an on-chain cancel does not fire a subscription.cancelled webhook today. If you need to react to it, poll subscriptions.retrieve or subscriptions.list.

Building a cancel button for your customers

Most products give customers a cancel button in their own app:

1. Build the page in your app.
2. Authenticate the customer the way you already do.
3. From your server, call strimz.subscriptions.cancel({ id, reason }) with your secret key.

The secret key stays on your server. See Self-serve cancel for a full example.

Refunding unused time

Cancelling does not refund anything. If you want to give back the unused part of the current period, issue a refund against the last charge's transaction. There is no automatic proration, because the right amount depends on your pricing, discounts and tax rules.

A simple prorated amount:

const periodMs = Date.parse(sub.currentPeriodEndAt) - Date.parse(sub.currentPeriodStartAt)
const unusedMs = Math.max(0, Date.parse(sub.currentPeriodEndAt) - Date.now())
const refundAmount = (BigInt(sub.amount) * BigInt(unusedMs)) / BigInt(periodMs)

Then issue the refund from the dashboard's Refunds page, where your Strimz wallet signs the transfer. From code, strimz.refunds.create returns the refund and the transfer to sign; see Process a refund.

Allowances

Cancelling does not revoke the payer's token allowance to the subscriptions contract. The contract refuses to charge a cancelled subscription, so the leftover allowance cannot be used for it. A payer who wants to remove it can call approve(strimzSubscriptions, 0) on the token from their wallet.