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.

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.

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

Parameters

Name	Type	Description
subscription_id	string	Required. The ID of the subscription to add this item to.
price_id	string	Required. The ID of the price to subscribe the customer to.
quantity	number	The quantity of the price. Defaults to 1.
billing_thresholds	object	Usage-based billing thresholds for this item.
metadata	object	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns the newly created TSubscriptionItem object.

Retrieve a Subscription Item#

Retrieves the details of an existing subscription item.

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

Parameters

Name	Type	Description
id	string	Required. The unique identifier of the subscription item to retrieve.

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.

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

Parameters

Name	Type	Description
id	string	Required. The ID of the subscription item to update.
updates	object	An object containing the fields to update.

Updateable Fields

Name	Type	Description
price_id	string	The ID of the new price for this item.
quantity	number	The new quantity for this item.
billing_thresholds	object	Usage-based billing thresholds for this item.
metadata	object	A set of key-value pairs to update.

Returns

Returns the updated TSubscriptionItem object.

List Subscription Items#

Returns a list of subscription items for a given subscription.

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

Parameters

Name	Type	Description
subscription_id	string	Required. The ID of the subscription whose items you want to list.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items to return per page. Defaults to 20.

Returns

A paginated list of TSubscriptionItemExpanded objects.

Delete a Subscription Item#

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

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

Parameters

Name	Type	Description
id	string	Required. The ID of the subscription item to delete.
body.clear_usage	boolean	If true, all usage records for a metered price will be cleared. Defaults to false.

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.

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

Parameters

Name	Type	Description
subscription_item_id	string	Required. The ID of the subscription item to report usage for.
quantity	number	Required. The quantity of usage to report. Must be a positive integer.
action	string	Determines how the reported quantity is applied. Can be increment (adds to existing usage) or set (overwrites usage at the given timestamp). Defaults to increment.
timestamp	number	The UNIX timestamp for the usage event. Must be within the current billing period. Defaults to the current time.

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).

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

Parameters

Name	Type	Description
subscription_item_id	string	Required. The ID of the subscription item.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items to return per page. Defaults to 20.

Returns

A paginated list of TUsageRecordSummary objects.

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.

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

Parameters

Name	Type	Description
subscription_item_id	string	Required. The ID of the subscription item.
start	number	A UNIX timestamp to filter usage records after this time.
end	number	A UNIX timestamp to filter usage records before or at this time.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items to return per page. Defaults to 20.

Returns

A paginated list of TUsageRecord objects.

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
}