Stripe: Retrieve a subscription item

← Subscription items operations · Get started

Operation stripe.getsubscriptionitemsitem

Provider route: GET /v1/subscription_items/{item}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["subscriptionItems"]["getSubscriptionItemsItem"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.subscriptionItems.getSubscriptionItemsItem(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.subscription_items.get_subscription_items_item(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.item	string	Required within parent	Maximum length: 5000
query	object	Optional	Additional keys: not allowed
query.expand	array	Optional
query.expand[]	string	Each item	Maximum length: 5000

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a subscription item — response body

Referenced models: Create a subscription item — response body

Schemas

706 more schemas are linked from the tables above, on the schema pages.

Create a subscription item — response body

Field	Type	Presence	Description and constraints
$	object	Root	Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.
billed_until	JSON	Optional
billed_until (anyOf 1)	integer	Alternative	The time period the subscription item has been billed for. Format: unix-time
billed_until (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
billing_thresholds	JSON	Optional
billing_thresholds (anyOf 1)	JSON	Alternative	Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
billing_thresholds (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a subscription item — response body — billing thresholds value usage gte
billing_thresholds (anyOf 2)	null	Alternative
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch.
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
current_period_end	JSON	Required within parent
current_period_end (anyOf 1)	integer	Alternative	The end time of this subscription item's current billing period. Format: unix-time
current_period_end (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
current_period_start	JSON	Required within parent
current_period_start (anyOf 1)	integer	Alternative	The start time of this subscription item's current billing period. Format: unix-time
current_period_start (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
current_trial	JSON	Optional
current_trial (anyOf 1)	JSON	Alternative	The current trial that is applied to this subscription item.
current_trial (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a subscription item — response body — current trial value end date, start date, trial offer
current_trial (anyOf 2)	null	Alternative
discounts	array	Required within parent	The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
discounts[]	JSON	Each item
discounts[] (anyOf 1)	string	Alternative	Maximum length: 5000
discounts[] (anyOf 2)	Model	Alternative	Expand Get Customers Customer Discount — response body
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
metadata	object	Required within parent	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: subscription_item
price	Model	Required within parent	Expand Create a price — response body
quantity	JSON	Optional
quantity (anyOf 1)	integer	Alternative	The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
quantity (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
subscription	string	Required within parent	The `subscription` this `subscription_item` belongs to. Maximum length: 5000
tax_rates	JSON	Optional
tax_rates (anyOf 1)	array	Alternative	The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.
tax_rates (anyOf 1)[]	Model	Each item	Expand Create a tax rate — response body
tax_rates (anyOf 2)	null	Alternative

Referenced models: Get Customers Customer Discount — response body, Create a price — response body, Create a subscription item — response body — billing thresholds value usage gte, Create a subscription item — response body — current trial value end date, start date, trial offer, Create a tax rate — response body

Get Customers Customer Discount — response body

Field	Type	Presence	Description and constraints
$	object	Root	A discount represents the actual application of a [coupon](https://docs.stripe.com/api#coupons) or [promotion code](https://docs.stripe.com/api#promotion_codes). It contains information about when the discount began, when it will end, and what it is applied to. Related guide: [Applying discounts to subscriptions](https://docs.stripe.com/billing/subscriptions/discounts)
checkout_session	JSON	Optional
checkout_session (anyOf 1)	string	Alternative	The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode. Maximum length: 5000
checkout_session (anyOf 2)	null	Alternative
customer	JSON	Optional
customer (anyOf 1)	JSON	Alternative	The ID of the customer associated with this discount.
customer (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
customer (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a customer — response body
customer (anyOf 1) (anyOf 3)	Model	Alternative	Expand Delete a customer — response body
customer (anyOf 2)	null	Alternative
customer_account	JSON	Optional
customer_account (anyOf 1)	string	Alternative	The ID of the account representing the customer associated with this discount. Maximum length: 5000
customer_account (anyOf 2)	null	Alternative
end	JSON	Optional
end (anyOf 1)	JSON	Alternative
end (anyOf 1) (anyOf 1)	integer	Alternative	If the coupon has a duration of `repeating`, the date that this discount will end. If the coupon has a duration of `once` or `forever`, this attribute will be null. Format: unix-time
end (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
end (anyOf 2)	null	Alternative
id	string	Required within parent	The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array. Maximum length: 5000
invoice	JSON	Optional
invoice (anyOf 1)	string	Alternative	The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice. Maximum length: 5000
invoice (anyOf 2)	null	Alternative
invoice_item	JSON	Optional
invoice_item (anyOf 1)	string	Alternative	The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item. Maximum length: 5000
invoice_item (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: discount
promotion_code	JSON	Optional
promotion_code (anyOf 1)	JSON	Alternative	The promotion code applied to create this discount.
promotion_code (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
promotion_code (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a promotion code — response body
promotion_code (anyOf 2)	null	Alternative
source	Model	Required within parent	Expand Get Customers Customer Discount — response body — source
start	JSON	Required within parent
start (anyOf 1)	integer	Alternative	Date that the coupon was applied. Format: unix-time
start (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
subscription	JSON	Optional
subscription (anyOf 1)	string	Alternative	The subscription that this coupon is applied to, if it is applied to a particular subscription. Maximum length: 5000
subscription (anyOf 2)	null	Alternative
subscription_item	JSON	Optional
subscription_item (anyOf 1)	string	Alternative	The subscription item that this coupon is applied to, if it is applied to a particular subscription item. Maximum length: 5000
subscription_item (anyOf 2)	null	Alternative

Referenced models: Create a customer — response body, Delete a customer — response body, Get Customers Customer Discount — response body — source, Create a promotion code — response body

Create a product — response body — marketing features item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Optional	The marketing feature name. Up to 80 characters long. Maximum length: 5000

Policy, approvals and errors

SDK function policy ID: stripe.getsubscriptionitemsitem. Catalog operation: GetSubscriptionItemsItem. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source