subscription.getStatus

Check the status and details of an existing subscription

Defined in the Base Account SDK

The subscription.getStatus function retrieves the current status and details of a subscription created with spend permissions. Use this to check if a subscription is active, view remaining charges, and determine the next payment period.

Parameters

id · string · required

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

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

testnet · boolean

Must match the testnet setting used in the original subscribe call. Default: false

Returns

result · SubscriptionStatus

Subscription status information including current state and payment details.

Show SubscriptionStatus properties

isSubscribed · boolean

Whether subscription is active (not cancelled).

recurringCharge · string

Recurring charge amount in USD.

remainingChargeInPeriod · string

Remaining amount that can be charged in the current period.

currentPeriodStart · Date

Start date of the current billing period.

nextPeriodStart · Date

Start date of the next billing period.

periodInDays · number

Subscription period in days.

Basic Status Check

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

const status = await base.subscription.getStatus({
  id: '0x71319cd488f8e4f24687711ec5c95d9e0c1bacbf5c1064942937eba4c7cf2984',
  testnet: false
});

console.log(`Active: ${status.isSubscribed}`);
console.log(`Recurring amount: $${status.recurringCharge}`);
console.log(`Remaining this period: $${status.remainingChargeInPeriod}`);
console.log(`Next payment: ${status.nextPeriodStart}`);

Active Subscription

{
  isSubscribed: true,
  recurringCharge: "9.99",
  remainingChargeInPeriod: "9.99",
  currentPeriodStart: "2024-01-15T00:00:00.000Z",
  nextPeriodStart: "2024-02-14T00:00:00.000Z",
  periodInDays: 30
}

Usage Patterns

Check Before Charge

Always check subscription status before attempting to charge:

const status = await base.subscription.getStatus({ id, testnet });

if (status.isSubscribed && parseFloat(status.remainingChargeInPeriod!) > 0) {
  const chargeCalls = await base.subscription.prepareCharge({
    id,
    amount: status.remainingChargeInPeriod!,
    testnet
  });
}

Error Handling

The function may throw errors for invalid subscription IDs or network issues:

try {
  const status = await base.subscription.getStatus({
    id: subscriptionId,
    testnet: false
  });
  // Process status
} catch (error) {
  console.error(`Failed to get subscription status: ${error.message}`);
  // Handle error appropriately
}