;
};
Defined in the [Base Account SDK](https://github.com/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
The subscription ID (permission hash) returned from subscribe().
**Pattern:** `^0x[0-9a-fA-F]{64}$`
Must match the testnet setting used in the original subscribe call. Default: false
## Returns
Subscription status information including current state and payment details.
Whether subscription is active (not cancelled).
Recurring charge amount in USD.
Remaining amount that can be charged in the current period.
Start date of the current billing period.
Start date of the next billing period.
Subscription period in days.
```typescript Basic Status Check theme={null}
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}`);
```
```typescript Check Before Charging theme={null}
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
}
```
```typescript Active Subscription theme={null}
{
isSubscribed: true,
recurringCharge: "9.99",
remainingChargeInPeriod: "9.99",
currentPeriodStart: "2024-01-15T00:00:00.000Z",
nextPeriodStart: "2024-02-14T00:00:00.000Z",
periodInDays: 30
}
```
```typescript Partially Charged Subscription theme={null}
{
isSubscribed: true,
recurringCharge: "19.99",
remainingChargeInPeriod: "5.50",
currentPeriodStart: "2024-01-01T00:00:00.000Z",
nextPeriodStart: "2024-01-31T00:00:00.000Z",
periodInDays: 30
}
```
```typescript Cancelled Subscription theme={null}
{
isSubscribed: false,
recurringCharge: "9.99",
remainingChargeInPeriod: "0",
currentPeriodStart: "2024-01-15T00:00:00.000Z",
nextPeriodStart: "2024-02-14T00:00:00.000Z",
periodInDays: 30
}
```
```typescript Fully Charged Period theme={null}
{
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
Always check subscription status before attempting to charge:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript theme={null}
const status = await base.subscription.getStatus({ id, testnet });
return (
Next billing date: {new Date(status.nextPeriodStart).toLocaleDateString()}
);
```
## Error Handling
The function may throw errors for invalid subscription IDs or network issues:
```typescript theme={null}
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
}
```
(
We're updating the Base Privacy Policy, effective July 25, 2025, to reflect an expansion of Base services. Please review the updated policy here:{" "}
Base Privacy Policy
. By continuing to use Base services, you confirm that you have read and understand the updated policy.