API Reference

Subscription Items

Subscription items represent a specific product or service that a customer is subscribed to within a larger subscription. They link a price to a subscription and track details like quantity. This API allows you to manage these items individually, including reporting usage for metered billing.
For managing the overall subscription, please see the Subscriptions API documentation.
The Subscription Item Object#A subscription item object contains the details of a product within a subscription.
Attribute
Type
Description
id
string
Unique identifier for the subscription item.
livemode
boolean
true if the object exists in live mode, false if it exists in test mode.
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 subscribed to.
metadata
object
A set of key-value pairs that you can attach to an object. Useful for storing additional information.
billing_thresholds
object
Usage-based billing thresholds. Contains usage_gte.
created_at
date
Timestamp of when the object was created.
updated_at
date
Timestamp of the last update.
When retrieved, the price object will be expanded.
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 add this item to.
price_id
string
Required. The ID of the price to subscribe to.
quantity
number
The quantity of the price. Defaults to 1.
metadata
object
Key-value data to associate with the item.
billing_thresholds
object
Usage-based billing thresholds for this item.
Example
import payment from '@blocklet/payment-js';

async function addSubscriptionItem() {
  try {
    const subscriptionItem = await payment.subscriptionItems.create({
      subscription_id: 'sub_xxxxxxxxxxxxxx',
      price_id: 'price_xxxxxxxxxxxxxx',
      quantity: 2
    });
    console.log('Subscription Item created:', subscriptionItem);
  } catch (error) {
    console.error('Error creating subscription item:', error.message);
  }
}

addSubscriptionItem();Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "livemode": false,
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 2,
  "metadata": {},
  "billing_thresholds": null,
  "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
The unique identifier of the subscription item to retrieve.
Example
import payment from '@blocklet/payment-js';

async function getSubscriptionItem(itemId) {
  try {
    const subscriptionItem = await payment.subscriptionItems.retrieve(itemId);
    console.log('Retrieved Subscription Item:', subscriptionItem);
  } catch (error) {
    console.error('Error retrieving subscription item:', error.message);
  }
}

getSubscriptionItem('si_xxxxxxxxxxxxxx');Example Response (Expanded)
{
  "id": "si_xxxxxxxxxxxxxx",
  "livemode": false,
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "price": {
    "id": "price_xxxxxxxxxxxxxx",
    "product_id": "prod_xxxxxxxxxxxxxx",
    "active": true,
    "type": "recurring",
    "unit_amount": "1000",
    "currency_id": "usd",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    }
  },
  "quantity": 2,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Update a Subscription Item#Updates the parameters of a subscription item.
Parameters
Name
Type
Description
id
string
Required. The identifier of the subscription item to update.
quantity
number
The new quantity for the item.
price_id
string
The new price ID for the item.
metadata
object
New set of key-value data.
Example
import payment from '@blocklet/payment-js';

async function updateSubscriptionItem(itemId) {
  try {
    const updatedItem = await payment.subscriptionItems.update(itemId, {
      quantity: 3
    });
    console.log('Subscription Item updated:', updatedItem);
  } catch (error) {
    console.error('Error updating subscription item:', error.message);
  }
}

updateSubscriptionItem('si_xxxxxxxxxxxxxx');Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "livemode": false,
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 3,
  "metadata": {},
  "billing_thresholds": null,
  "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 to retrieve.
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of items per page. Defaults to 20.
order
string
A string representing the order of the results (e.g., 'created_at:ASC').
Example
import payment from '@blocklet/payment-js';

async function listSubscriptionItems(subscriptionId) {
  try {
    const items = await payment.subscriptionItems.list({ 
      subscription_id: subscriptionId, 
      pageSize: 5 
    });
    console.log(`Found ${items.count} items:`, items.list);
  } catch (error) {
    console.error('Error listing subscription items:', error.message);
  }
}

listSubscriptionItems('sub_xxxxxxxxxxxxxx');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "si_xxxxxxxxxxxxxx",
      "livemode": false,
      "subscription_id": "sub_xxxxxxxxxxxxxx",
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 3,
      "metadata": {},
      "created_at": "2023-10-27T10:00:00.000Z",
      "updated_at": "2023-10-27T10:05:00.000Z"
    }
  ]
}Delete a Subscription Item#Deletes an item from a subscription. This action is often irreversible.
Parameters
Name
Type
Description
id
string
The identifier of the subscription item to delete.
Example
import payment from '@blocklet/payment-js';

async function deleteSubscriptionItem(itemId) {
  try {
    const deletedItem = await payment.subscriptionItems.del(itemId);
    console.log('Subscription Item deleted:', deletedItem);
  } catch (error) {
    console.error('Error deleting subscription item:', error.message);
  }
}

deleteSubscriptionItem('si_xxxxxxxxxxxxxx');Example Response
{
  "id": "si_xxxxxxxxxxxxxx",
  "livemode": false,
  "subscription_id": "sub_xxxxxxxxxxxxxx",
  "price_id": "price_xxxxxxxxxxxxxx",
  "quantity": 3,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}Create a Usage Record#Creates a usage record for a metered billing subscription item. This is used to report usage that will be billed at the end of a period.
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
Can be 'increment' to add to the existing usage, or 'set' to overwrite it. Defaults to 'increment'.
timestamp
number
The timestamp for the usage event. Defaults to the current time.
Example
import payment from '@blocklet/payment-js';

async function reportUsage(itemId) {
  try {
    const usageRecord = await payment.subscriptionItems.createUsageRecord({
      subscription_item_id: itemId,
      quantity: 100,
      action: 'increment'
    });
    console.log('Usage Record created:', usageRecord);
  } catch (error) {
    console.error('Error creating usage record:', error.message);
  }
}

reportUsage('si_metered_xxxxxxxx');Example Response
{
  "id": "ur_xxxxxxxxxxxxxx",
  "livemode": false,
  "quantity": 100,
  "subscription_item_id": "si_metered_xxxxxxxx",
  "timestamp": 1672531200
}List Usage Record Summaries#For a given subscription item, returns a list of summary objects. Each object in the list contains a total quantity of usage reported for a specific period.
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 per page. Defaults to 20.
order
string
A string representing the order of the results.
Example
import payment from '@blocklet/payment-js';

async function getUsageSummaries(itemId) {
  try {
    const summaries = await payment.subscriptionItems.listUsageRecordSummaries({ 
      subscription_item_id: itemId
    });
    console.log('Usage Summaries:', summaries);
  } catch (error) {
    console.error('Error listing usage summaries:', error.message);
  }
}

getUsageSummaries('si_metered_xxxxxxxx');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "si_metered_xxxxxxxx",
      "total_usage": 5000
    }
  ]
}
You now have the tools to manage individual items within a subscription. For handling payment-related events, proceed to the Webhooks documentation.

Attribute	Type	Description
`id`	`string`	Unique identifier for the subscription item.
`livemode`	`boolean`	`true` if the object exists in live mode, `false` if it exists in test mode.
`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 subscribed to.
`metadata`	`object`	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
`billing_thresholds`	`object`	Usage-based billing thresholds. Contains `usage_gte`.
`created_at`	`date`	Timestamp of when the object was created.
`updated_at`	`date`	Timestamp of the last update.

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 to.
`quantity`	`number`	The quantity of the price. Defaults to `1`.
`metadata`	`object`	Key-value data to associate with the item.
`billing_thresholds`	`object`	Usage-based billing thresholds for this item.

Name	Type	Description
`id`	`string`	Required. The identifier of the subscription item to update.
`quantity`	`number`	The new quantity for the item.
`price_id`	`string`	The new price ID for the item.
`metadata`	`object`	New set of key-value data.

Name	Type	Description
`subscription_id`	`string`	Required. The ID of the subscription whose items to retrieve.
`page`	`number`	The page number for pagination. Defaults to `1`.
`pageSize`	`number`	The number of items per page. Defaults to `20`.
`order`	`string`	A string representing the order of the results (e.g., `'created_at:ASC'`).

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`	Can be `'increment'` to add to the existing usage, or `'set'` to overwrite it. Defaults to `'increment'`.
`timestamp`	`number`	The timestamp for the usage event. Defaults to the current time.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

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#

Subscriptions

Webhooks