Accept Subscriptions

Create a recurring USDC spend permission, check its status, and charge it safely from your backend.

A subscription is a revocable USDC spend permission. The customer approves a per-period maximum once; your backend checks the remaining allowance and charges only when payment is due.

Demo

Before rendering checkout, create the subscription-owner wallet with getOrCreateSubscriptionOwnerWallet() and expose only its public address to the browser.

1. Obtain customer approval

   SubscriptionButton.ts

   export async function subscribe(owner: Address) {
     const subscription = await browserBase.subscription.subscribe({
       recurringCharge: "29.99",
       subscriptionOwner: owner,
       periodInDays: 30,
       testnet: true,
     });
     await fetch("/api/subscriptions", {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ id: subscription.id, payer: subscription.subscriptionPayer }),
     });
     return subscription.id;
   }
   
2. Check and charge from the backend

   charge-subscription.ts

   export async function chargeSubscription(id: `0x${string}`, merchant: Address) {
     const status = await serverBase.subscription.getStatus({ id, testnet: true });
     if (!status.isSubscribed) throw new Error("Subscription is no longer active");
     if (Number(status.remainingChargeInPeriod ?? "0") <= 0) return { charged: false };
     const result = await serverBase.subscription.charge({
       id,
       amount: "max-remaining-charge",
       recipient: merchant,
       testnet: true,
       paymasterUrl: process.env.PAYMASTER_URL,
     });
     return { charged: true, transactionHash: result.id };
   }
   

Keep CDP credentials and wallet secrets on the server. Persist subscription IDs, make scheduled charges idempotent, stop retrying cancelled permissions, and distinguish an exhausted current period from a failed transaction.

The backend charges at most the remaining period allowance and records the returned transaction hash before marking the invoice paid.

See the complete verified subscription fixture for client and backend project setup.

See also

• Accept payments from humans
• subscribe() · charge()