API Reference

Subscription Items

Subscription items represent a specific product or service that a customer is subscribed to. They are essential components of a Subscription and are particularly important for metered billing, as usage is reported against a specific subscription item.
This API allows you to manage the individual items within a subscription and report usage for them.
The Subscription Item Object#A Subscription Item object contains details about the product, price, and quantity for an item within a subscription.
{
  "id": "si_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 1,
  "billing_thresholds": null,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "price": {
    "id": "price_xxxxxxxxxxxxxx",
    "product_id": "prod_xxxxxxxxxxxxxx",
    "active": true,
    "type": "recurring",
    "unit_amount": 1000,
    "currency_id": "usd",
    "recurring": {
      "interval": "month",
      "interval_count": 1,
      "usage_type": "metered",
      "aggregate_usage": "sum"
    }
  }
}Create a Subscription Item#Adds a new item to an existing subscription.
Parameters
Name
Type
Description
subscription_id
string
Required. The ID of the subscription to which this item should be added.
price_id
string
Required. The ID of the price for this item.
quantity
number
The quantity of the subscription item. 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 the object.
Example
const subscriptionItem = await payment.subscriptionItems.create({
  subscription_id: 'sub_xxxxxxxxxxxxxx',
  price_id: 'price_xxxxxxxxxxxxxx',
  quantity: 5
});

console.log(subscriptionItem);Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 5,
  "billing_thresholds": null,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Subscription Item#Retrieves the details of an existing subscription item.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the subscription item.
Example
const subscriptionItemId = 'si_xxxxxxxxxxxxxx';
const subscriptionItem = await payment.subscriptionItems.retrieve(subscriptionItemId);

console.log(subscriptionItem);Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 5,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "price": {
    "id": "price_xxxxxxxxxxxxxx",
    "product_id": "prod_xxxxxxxxxxxxxx",
    "active": true,
    "type": "recurring",
    "unit_amount": 1000,
    "currency_id": "usd"
  }
}Update a Subscription Item#Updates the properties of a subscription item.
Parameters
Name
Type
Description
id
string
Required. The ID of the subscription item to update.
price_id
string
The ID of the price to set for this item.
quantity
number
The quantity of the subscription item.
billing_thresholds
object
Usage-based billing thresholds for this item.
metadata
object
A set of key-value pairs that you can attach to the object.
Example
const subscriptionItemId = 'si_xxxxxxxxxxxxxx';
const updatedItem = await payment.subscriptionItems.update(subscriptionItemId, {
  quantity: 10
});

console.log(updatedItem);Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 10,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}List Subscription Items#Returns a list of subscription items for a given subscription.
Parameters
Name
Type
Description
subscription_id
string
Required. The ID of the subscription whose items you want to list.
price_id
string
The ID of the price to filter by.
page
number
The page number for pagination, starting at 1. Defaults to 1.
pageSize
number
The number of items to return per page. Defaults to 20.
Example
const subscriptionId = 'sub_xxxxxxxxxxxxxx';
const items = await payment.subscriptionItems.list({ 
  subscription_id: subscriptionId,
  pageSize: 5 
});

console.log(items);Example Response
{
  "count": 1,
  "list": [
    {
      "id": "si_xxxxxxxxxxxxxx",
      "subscription_id": "sub_xxxxxxxxxxxxxx",
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 10
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}Delete a Subscription Item#Deletes an item from a subscription. This action is often irreversible.
Parameters
Name
Type
Description
id
string
Required. The ID of the subscription item to delete.
clear_usage
boolean
If true, and the item's price is metered, this will also delete all associated usage records. Defaults to false.
Example
const subscriptionItemId = 'si_xxxxxxxxxxxxxx';
const deletedItem = await payment.subscriptionItems.del(subscriptionItemId, {
  clear_usage: true
});

console.log(deletedItem);Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 10
}Create a Usage Record#Creates a usage record for a specified subscription item. This is used for reporting usage for metered billing.
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.
action
string
Either increment or set. increment adds to the existing usage, while set overwrites it. Defaults to increment.
timestamp
number
A Unix timestamp representing when the usage occurred. It must be within the current billing period. Defaults to the current time.
Example
const usageRecord = await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxxxxxxxxxxxxx',
  quantity: 100,
  action: 'increment'
});

console.log(usageRecord);Example Response
{
  "id": "ur_xxxxxxxxxxxxxx",
  "subscription_item_id": "si_xxxxxxxxxxxxxx",
  "quantity": 100,
  "timestamp": 1672531200,
  "livemode": false
}List Usage Record Summaries#For a given subscription item, returns a list of usage summaries for each invoice period.
Parameters
Name
Type
Description
subscription_item_id
string
Required. The ID of the subscription item.
page
number
The page number for pagination, starting at 1. Defaults to 1.
pageSize
number
The number of items to return per page. Defaults to 20.
Example
const subscriptionItemId = 'si_xxxxxxxxxxxxxx';
const summaries = await payment.subscriptionItems.listUsageRecordSummaries({ 
  subscription_item_id: subscriptionItemId
});

console.log(summaries);Example Response
{
  "count": 1,
  "list": [
    {
      "livemode": false,
      "invoice_id": "in_xxxxxxxxxxxxxx",
      "subscription_item_id": "si_xxxxxxxxxxxxxx",
      "total_usage": 1500,
      "period": {
        "start": 1672531200,
        "end": 1675209600
      }
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}List Usage Records#Retrieves a list of individual usage records for a subscription item.
Parameters
Name
Type
Description
subscription_item_id
string
Required. The ID of the subscription item whose usage records you want to list.
start
number
A Unix timestamp to filter records created after this time. Defaults to the start of the current period.
end
number
A Unix timestamp to filter records created before or at this time. Defaults to the end of the current period.
page
number
The page number for pagination, starting at 1. Defaults to 1.
pageSize
number
The number of items to return per page. Defaults to 20.
Example
const subscriptionItemId = 'si_xxxxxxxxxxxxxx';
const records = await payment.subscriptionItems.listUsageRecords({ 
  subscription_item_id: subscriptionItemId
});

console.log(records);Example Response
{
  "count": 2,
  "list": [
    {
      "id": "ur_xxxxxxxxxxxxxx",
      "subscription_item_id": "si_xxxxxxxxxxxxxx",
      "quantity": 100,
      "timestamp": 1672531200
    },
    {
      "id": "ur_yyyyyyyyyyyyyy",
      "subscription_item_id": "si_xxxxxxxxxxxxxx",
      "quantity": 50,
      "timestamp": 1672617600
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}This guide covers the management of subscription items and their associated usage records. For more details on overall subscription management, see the Subscriptions documentation.

Name	Type	Description
`subscription_id`	`string`	Required. The ID of the subscription to which this item should be added.
`price_id`	`string`	Required. The ID of the price for this item.
`quantity`	`number`	The quantity of the subscription item. 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 the object.

Name	Type	Description
`id`	`string`	Required. The ID of the subscription item to update.
`price_id`	`string`	The ID of the price to set for this item.
`quantity`	`number`	The quantity of the subscription item.
`billing_thresholds`	`object`	Usage-based billing thresholds for this item.
`metadata`	`object`	A set of key-value pairs that you can attach to the object.

Name	Type	Description
`subscription_id`	`string`	Required. The ID of the subscription whose items you want to list.
`price_id`	`string`	The ID of the price to filter by.
`page`	`number`	The page number for pagination, starting at 1. Defaults to 1.
`pageSize`	`number`	The number of items to return per page. Defaults to 20.

Name	Type	Description
`id`	`string`	Required. The ID of the subscription item to delete.
`clear_usage`	`boolean`	If `true`, and the item's price is metered, this will also delete all associated usage records. Defaults to `false`.

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.
`action`	`string`	Either `increment` or `set`. `increment` adds to the existing usage, while `set` overwrites it. Defaults to `increment`.
`timestamp`	`number`	A Unix timestamp representing when the usage occurred. It must be within the current billing period. Defaults to the current time.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Subscription Items

The Subscription Item Object#

Create a Subscription Item#

Retrieve a Subscription Item#

Update a Subscription Item#

List Subscription Items#

Delete a Subscription Item#

Create a Usage Record#

List Usage Record Summaries#

List Usage Records#

Subscriptions

Refunds