subscription.revoke

Revoke subscriptions from your backend using CDP server wallets

Defined in the Base Account SDK

Node.js Only: This function uses CDP (Coinbase Developer Platform) server wallets and is only available in Node.js environments. For browser/client-side applications, use prepareRevoke instead.

The revoke function cancels subscriptions automatically from your backend. It uses a CDP smart wallet as the subscription owner to execute the revocation transaction, handling all details including wallet management, transaction signing, and optional gas sponsorship.

How It Works

When you call revoke(), the function:

1. Initializes a CDP client with your credentials
2. Retrieves the existing smart wallet (subscription owner)
3. Prepares the revoke transaction call
4. Executes the revocation using the smart wallet
5. Optionally uses a paymaster for gas sponsorship
6. Returns the transaction hash

Parameters

id · string · required

The subscription ID (permission hash) returned from subscribe().

Pattern: ^0x[0-9a-fA-F]{64}$

testnet · boolean

Whether to use Base Sepolia testnet. Must match the network used in subscribe(). Default: false

cdpApiKeyId · string

CDP API key ID. Falls back to CDP_API_KEY_ID environment variable.

cdpApiKeySecret · string

CDP API key secret. Falls back to CDP_API_KEY_SECRET environment variable.

cdpWalletSecret · string

CDP wallet secret. Falls back to CDP_WALLET_SECRET environment variable.

walletName · string

Optional custom wallet name for the CDP smart wallet. Default: “subscription owner”

Use Default: Most applications should omit this parameter and use the default. Only specify if you used a custom name in getOrCreateSubscriptionOwnerWallet().

paymasterUrl · string

Paymaster URL for transaction sponsorship (gasless transactions). Falls back to PAYMASTER_URL environment variable.

Returns

result · RevokeResult

Revoke execution result.

Show RevokeResult properties

success · true

Always true on successful revocation.

id · string

Transaction hash of the revocation.

subscriptionId · string

The subscription ID that was revoked.

subscriptionOwner · Address

Address of the wallet that executed the revocation.

Setup

Before using revoke(), you need CDP credentials. Get them from the CDP Portal.

Set as environment variables:

export CDP_API_KEY_ID="your-api-key-id"
export CDP_API_KEY_SECRET="your-api-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"

Or pass directly as parameters (see examples below).

Basic Revoke with Environment Variables

import { base } from '@base-org/account/node';

// Requires: CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET env vars
const result = await base.subscription.revoke({
  id: '0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984'
});

console.log(`Revoked subscription: ${result.id}`);
console.log(`Transaction: ${result.id}`);

import { base } from '@base-org/account/node';

const result = await base.subscription.revoke({
  id: '0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984',
  cdpApiKeyId: 'your-api-key-id',
  cdpApiKeySecret: 'your-api-key-secret',
  cdpWalletSecret: 'your-wallet-secret',
  testnet: false
});

console.log(`Subscription revoked: ${result.subscriptionId}`);

import { base } from '@base-org/account/node';

// Use a paymaster to sponsor gas fees
const result = await base.subscription.revoke({
  id: subscriptionId,
  paymasterUrl: 'https://api.developer.coinbase.com/rpc/v1/base/your-key',
  testnet: false
});

console.log(`Gasless revocation: ${result.id}`);

import { base } from '@base-org/account/node';

// Only needed if you used a custom name in getOrCreateSubscriptionOwnerWallet()
const result = await base.subscription.revoke({
  id: subscriptionId,
  walletName: 'premium-subscriptions-wallet', // Must match wallet creation
  testnet: false
});

Success Response

{
  success: true,
  id: "0x8f3d9e2a1b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e",
  subscriptionId: "0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984",
  subscriptionOwner: "0xYourSubscriptionOwnerWallet"
}

Error Handling

Always wrap revoke() calls in try-catch blocks:

try {
  const result = await base.subscription.revoke({
    id: subscriptionId,
    testnet: false
  });
  
  console.log(`Successfully revoked: ${result.id}`);
  
  // Update your database
  await updateSubscriptionRecord(subscriptionId, {
    status: 'cancelled',
    revokedAt: new Date(),
    revocationTx: result.id
  });
  
} catch (error) {
  console.error(`Failed to revoke subscription: ${error.message}`);
  
  // Handle specific error cases
  if (error.message.includes('not found')) {
    console.log('Subscription already cancelled or not found');
  } else if (error.message.includes('CDP')) {
    console.log('CDP credentials issue');
  }
}

Common Use Cases

User Cancellation Request

async function handleUserCancellation(userId: string, subscriptionId: string) {
  try {
    // Revoke the subscription
    const result = await base.subscription.revoke({
      id: subscriptionId,
      testnet: false
    });
    
    // Update database
    await db.updateSubscription(subscriptionId, {
      status: 'cancelled',
      cancelledBy: 'user',
      cancelledAt: new Date(),
      revocationTx: result.id
    });
    
    // Notify user
    await sendEmail(userId, {
      subject: 'Subscription Cancelled',
      body: `Your subscription has been successfully cancelled.`
    });
    
    return { success: true };
  } catch (error) {
    console.error('Cancellation failed:', error);
    throw error;
  }
}

Policy Violation

async function revokeForViolation(subscriptionId: string, reason: string) {
  try {
    // Revoke immediately
    const result = await base.subscription.revoke({
      id: subscriptionId,
      testnet: false
    });
    
    // Log violation
    await db.logViolation({
      subscriptionId,
      reason,
      action: 'revoked',
      transactionHash: result.id,
      timestamp: new Date()
    });
    
    console.log(`Revoked subscription due to: ${reason}`);
  } catch (error) {
    console.error('Revocation failed:', error);
  }
}

Administrative Action

async function bulkRevokeExpiredTrials() {
  const expiredTrials = await db.getExpiredTrialSubscriptions();
  
  for (const trial of expiredTrials) {
    try {
      const result = await base.subscription.revoke({
        id: trial.subscriptionId,
        testnet: false
      });
      
      await db.updateSubscription(trial.id, {
        status: 'trial_expired',
        revokedAt: new Date(),
        revocationTx: result.id
      });
      
      console.log(`✅ Revoked expired trial: ${trial.id}`);
    } catch (error) {
      console.error(`Failed to revoke trial ${trial.id}:`, error.message);
    }
  }
}

Common Errors

Missing CDP Credentials

Failed to initialize CDP client for subscription revoke

Solution: Ensure CDP_API_KEY_ID, CDP_API_KEY_SECRET, and CDP_WALLET_SECRET are set as environment variables or passed as parameters.

Subscription Not Found

Subscription with ID 0x... not found

Solution: Check that the subscription ID is correct. The subscription may have already been revoked or never existed.

Wallet Does Not Exist

Wallet "subscription owner" does not exist

Solution: The CDP wallet hasn’t been created yet. First call getOrCreateSubscriptionOwnerWallet to set up the wallet.

Already Revoked

If a subscription is already revoked, calling revoke() again may fail. Check status first using getSubscriptionStatus.

Important Notes

Permanent Action: Revoking a subscription is permanent and cannot be undone. The user would need to create a new subscription to re-enable charging.

User-Initiated Revocation: Users can also revoke subscriptions themselves from their wallet. Your backend should handle subscription status checks before attempting charges.

When to Use Revoke

Use revoke() from your backend when you need to programmatically cancel subscriptions:

• User requests cancellation through your application
• Policy violations or terms of service breaches
• Failed payments after multiple retry attempts
• Account closure or service termination
• Trial period expiration without conversion
• Administrative actions or bulk operations

Related Functions

Setup Wallet

Create CDP wallet before revoking

Check Status

Verify subscription before revoking

Custom Revoke

Advanced manual execution