Subscriptions

Set the subscription terms#

A subscription sets its merchant and refund receiver, amount per period, duration, start, expiry, maximum periods and budget. Each onchain charge pays a period. The manager reports whether access is paid and when that paid period ends.

Use that result to decide service access. Your application still issues its sessions, records jobs and handles outages; a paid period cannot show whether the service was delivered.

Configure a backend#

Supply a deployment manifest with the chain, core and asset runtime hashes and token decimals. Use the same provider object for the reader and signer. Opening the subscription funds it in a transaction, after the payer approves token allowance.

With private funding, the escrow is the payer. It controls cancellation. Use the subscription manager for period access and the funding driver for escrow cancellation and refund forwarding.

Charge a period and check access#

Import the CommonJS exports below from the protocol checkout. The host supplies the deployment manifest, provider, funded terms and durable store used by this example.

const {
  createSubscriptionBackend, createSubscriptionManager,
} = require("./sdk/payment-sessions/index.cjs");
const backend = createSubscriptionBackend({
  ...subscriptionDeployment, provider, signer: payerSigner,
});
const subscription = createSubscriptionManager({
  backend, store: subscriptionStore,
  terms: { subscriptionId, ...subscriptionTerms },
});
await subscription.tick();
const access = await subscription.access();
if (access.allowed) console.log(access.paidUntil);

Cancel or retry a charge#

For public payer funding, use the manager's cancellation interface. For private funding, call the funding driver: an ephemeral authorization key cannot act as the escrow payer.

If a charge times out, read its period state before ticking again. Keep records for paid access, refunded funds and completed service work so you can see which part succeeded.