Subscription Items

Subscription Items represent a specific product and price that a customer is subscribed to. They are components of a Subscription and are essential for managing recurring billing, especially for plans with metered usage.

This API allows you to create, retrieve, update, and delete subscription items. Crucially, it also provides methods for reporting usage for metered billing.

The Subscription Item Object

A Subscription Item object contains details about a specific item within a subscription.

The TSubscriptionItemExpanded Object

interface TSubscriptionItemExpanded {
  id: string; // Unique identifier for the subscription item
  subscription_id: string; // The ID of the subscription this item belongs to
  price_id: string; // The ID of the price associated with this item
  quantity: number; // The quantity of the price
  billing_thresholds: object | null; // Usage-based billing thresholds
  metadata: object | null; // A set of key-value pairs for additional information
  created_at: number; // Timestamp of creation
  updated_at: number; // Timestamp of last update
  price: TPrice; // The expanded Price object
}

Create a Subscription Item

Adds a new item (a product and price) to an existing subscription.

Create Subscription Item

const subscriptionItem = await payment.subscriptionItems.create({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
  price_id: 'price_xxxxxxxxxxxxxx',
  quantity: 1,
});

Parameters

Returns

Returns the newly created TSubscriptionItem object.

Retrieve a Subscription Item

Retrieves the details of an existing subscription item.

Retrieve Subscription Item

const subscriptionItem = await payment.subscriptionItems.retrieve(
  'si_xxxxxxxxxxxxxx' // Subscription Item ID
);

Parameters

Returns

Returns a TSubscriptionItemExpanded object if a valid ID was provided.

Update a Subscription Item

Updates the properties of a subscription item. You can update the price_id, quantity, and metadata.

Update Subscription Item

const subscriptionItem = await payment.subscriptionItems.update(
  'si_xxxxxxxxxxxxxx', // Subscription Item ID
  {
    quantity: 2,
  }
);

Parameters

Updateable Fields

Returns

Returns the updated TSubscriptionItem object.

List Subscription Items

Returns a list of subscription items for a given subscription.

List Subscription Items

const subscriptionItems = await payment.subscriptionItems.list({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
});

Parameters

Returns

A paginated list of TSubscriptionItemExpanded objects.

Delete a Subscription Item

Deletes an item from a subscription. This is a permanent action.

Delete Subscription Item

const deletedItem = await payment.subscriptionItems.del(
  'si_xxxxxxxxxxxxxx', // Subscription Item ID
  {
    clear_usage: true, // Optional
  }
);

Parameters

Returns

Returns the deleted TSubscriptionItem object.

Create a Usage Record

For metered prices, you must report usage to bill your customers correctly. This method creates a usage record for a specified subscription item.

Create Usage Record

const usageRecord = await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
  quantity: 100,
  action: 'increment',
  timestamp: Math.floor(Date.now() / 1000),
});

Parameters

Returns

Returns the created TUsageRecord object.

List Usage Record Summaries

For a given subscription item, returns a list of usage record summaries, aggregated by billing period (invoice).

List Usage Record Summaries

const summaries = await payment.subscriptionItems.listUsageRecordSummaries({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});

Parameters

Returns

A paginated list of TUsageRecordSummary objects.

The TUsageRecordSummary Object

interface TUsageRecordSummary {
  invoice_id: string; // ID of the invoice for this period
  subscription_item_id: string;
  total_usage: number; // Total usage for the period
  period: {
    start: number; // Start of the billing period (UNIX timestamp)
    end: number; // End of the billing period (UNIX timestamp)
  };
}

List Usage Records

Retrieves a list of individual usage records for a subscription item. This provides a detailed, non-aggregated view of all reported usage.

List Usage Records

const records = await payment.subscriptionItems.listUsageRecords({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
});

Parameters

Returns

A paginated list of TUsageRecord objects.

The TUsageRecord Object

interface TUsageRecord {
  id: string;
  subscription_item_id: string;
  quantity: number;
  timestamp: number; // UNIX timestamp of the record
  billed: boolean; // Whether this usage has been billed
}