subscription.getStatus - Base Documentation

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

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

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

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

// Check if subscription can be charged
const status = await base.subscription.getStatus({
  id: subscriptionId,
  testnet: false
});

if (!status.isSubscribed) {
  console.log("Subscription has been cancelled");
  return;
}

const remainingAmount = parseFloat(status.remainingChargeInPeriod || '0');
const chargeAmount = parseFloat(status.recurringCharge);

if (remainingAmount >= chargeAmount) {
  console.log(`Can charge full amount: $${chargeAmount}`);
  // Proceed with charge
} else if (remainingAmount > 0) {
  console.log(`Can only charge remaining: $${remainingAmount}`);
  // Charge partial amount
} else {
  console.log(`No remaining charge until ${status.nextPeriodStart}`);
  // Wait for next period
}

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

{
  isSubscribed: true,
  recurringCharge: "19.99",
  remainingChargeInPeriod: "5.50",
  currentPeriodStart: "2024-01-01T00:00:00.000Z",
  nextPeriodStart: "2024-01-31T00:00:00.000Z",
  periodInDays: 30
}

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

{
  isSubscribed: true,
  recurringCharge: "49.99",
  remainingChargeInPeriod: "0",
  currentPeriodStart: "2024-01-01T00:00:00.000Z",
  nextPeriodStart: "2024-02-01T00:00:00.000Z",
  periodInDays: 31
}

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

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.

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

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

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

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

// Check if subscription can be charged
const status = await base.subscription.getStatus({
  id: subscriptionId,
  testnet: false
});

if (!status.isSubscribed) {
  console.log("Subscription has been cancelled");
  return;
}

const remainingAmount = parseFloat(status.remainingChargeInPeriod || '0');
const chargeAmount = parseFloat(status.recurringCharge);

if (remainingAmount >= chargeAmount) {
  console.log(`Can charge full amount: $${chargeAmount}`);
  // Proceed with charge
} else if (remainingAmount > 0) {
  console.log(`Can only charge remaining: $${remainingAmount}`);
  // Charge partial amount
} else {
  console.log(`No remaining charge until ${status.nextPeriodStart}`);
  // Wait for next period
}

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

{
  isSubscribed: true,
  recurringCharge: "19.99",
  remainingChargeInPeriod: "5.50",
  currentPeriodStart: "2024-01-01T00:00:00.000Z",
  nextPeriodStart: "2024-01-31T00:00:00.000Z",
  periodInDays: 30
}

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

{
  isSubscribed: true,
  recurringCharge: "49.99",
  remainingChargeInPeriod: "0",
  currentPeriodStart: "2024-01-01T00:00:00.000Z",
  nextPeriodStart: "2024-02-01T00:00:00.000Z",
  periodInDays: 31
}

Usage Patterns

Check Before Charge
Schedule Next Charge
Display to User

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
  });
}

Use the status to schedule when to charge next:

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

if (status.nextPeriodStart) {
  const nextChargeDate = new Date(status.nextPeriodStart);
  scheduleJob(nextChargeDate, () => chargeSubscription(id));
}

Show subscription details to users:

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

return (
  <div>
    <p>Status: {status.isSubscribed ? 'Active' : 'Cancelled'}</p>
    <p>Monthly charge: ${status.recurringCharge}</p>
    <p>Next billing date: {new Date(status.nextPeriodStart).toLocaleDateString()}</p>
  </div>
);

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
}

subscription.subscribe

subscription.charge

⌘I

​Parameters

​Returns

​Usage Patterns

​Error Handling

Parameters

Returns

Usage Patterns

Error Handling