Stripe: Create a subscription item

← Subscription items operations · Get started

Operation stripe.postsubscriptionitems

Provider route: POST /v1/subscription_items. 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"]["postSubscriptionItems"]>[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.postSubscriptionItems(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.post_subscription_items(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.billing_thresholds	JSON	Optional	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
body.billing_thresholds (anyOf 1)	object	Alternative
body.billing_thresholds (anyOf 1).usage_gte	integer	Required within parent
body.billing_thresholds (anyOf 2)	string	Alternative	One of:
body.current_trial	object	Optional	The trial offer to apply to this subscription item.
body.current_trial.trial_offer	string	Required within parent	Maximum length: 5000
body.discounts	JSON	Optional	The coupons to redeem into discounts for the subscription item.
body.discounts (anyOf 1)	array	Alternative
body.discounts (anyOf 1)[]	object	Each item
body.discounts (anyOf 1)[].coupon	string	Optional	Maximum length: 5000
body.discounts (anyOf 1)[].discount	string	Optional	Maximum length: 5000
body.discounts (anyOf 1)[].promotion_code	string	Optional	Maximum length: 5000
body.discounts (anyOf 2)	string	Alternative	One of:
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.metadata	object	Optional	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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.payment_behavior	string	Optional	Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`. One of: allow_incomplete, default_incomplete, error_if_incomplete, pending_if_incomplete
body.price	string	Optional	The ID of the price object. Maximum length: 5000
body.price_data	object	Optional	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline.
body.price_data.currency	string	Required within parent	Format: currency
body.price_data.product	string	Required within parent	Maximum length: 5000
body.price_data.recurring	object	Required within parent
body.price_data.recurring.interval	string	Required within parent	One of: day, month, week, year
body.price_data.recurring.interval_count	integer	Optional
body.price_data.tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
body.price_data.unit_amount	integer	Optional
body.price_data.unit_amount_decimal	string	Optional	Format: decimal
body.proration_behavior	string	Optional	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item’s `quantity` changes. The default value is `create_prorations`. One of: always_invoice, create_prorations, none
body.proration_date	integer	Optional	If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the [upcoming invoice](/api/invoices/create_preview) endpoint. Format: unix-time
body.quantity	integer	Optional	The quantity you’d like to apply to the subscription item you’re creating.
body.subscription	string	Required within parent	The identifier of the subscription to modify. Maximum length: 5000
body.tax_rates	JSON	Optional	A list of [Tax Rate](https://docs.stripe.com/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.
body.tax_rates (anyOf 1)	array	Alternative
body.tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
body.tax_rates (anyOf 2)	string	Alternative	One of:

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.postsubscriptionitems. Catalog operation: PostSubscriptionItems. 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