Stripe: Create a subscription — customers post Customers Customer Subscriptions

← Customers operations · Get started

Operation stripe.postcustomerscustomersubscriptions

Provider route: POST /v1/customers/{customer}/subscriptions. 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["customers"]["postCustomersCustomerSubscriptions"]>[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.customers.postCustomersCustomerSubscriptions(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.customers.post_customers_customer_subscriptions(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.customer	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.add_invoice_items	array	Optional	A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
body.add_invoice_items[]	Model	Each item	Expand Update a subscription — request body — body add invoice items item
body.application_fee_percent	JSON	Optional	A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner’s Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees [documentation](https://stripe.com/docs/connect/subscriptions#collecting-fees-on-subscriptions).
body.application_fee_percent (anyOf 1)	number	Alternative
body.application_fee_percent (anyOf 2)	string	Alternative	One of:
body.automatic_tax	object	Optional	Automatic tax settings for this subscription.
body.automatic_tax.enabled	boolean	Required within parent
body.automatic_tax.liability	object	Optional
body.automatic_tax.liability.account	string	Optional
body.automatic_tax.liability.type	string	Required within parent	One of: account, self
body.backdate_start_date	integer	Optional	A past timestamp to backdate the subscription’s start date to. If set, the first invoice will contain line items for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor. Format: unix-time
body.billing_cycle_anchor	integer	Optional	A future timestamp in UTC format to anchor the subscription’s [billing cycle](https://docs.stripe.com/subscriptions/billing-cycle). The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. Format: unix-time
body.billing_thresholds	JSON	Optional	Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
body.billing_thresholds (anyOf 1)	object	Alternative
body.billing_thresholds (anyOf 1).amount_gte	integer	Optional
body.billing_thresholds (anyOf 1).reset_billing_cycle_anchor	boolean	Optional
body.billing_thresholds (anyOf 2)	string	Alternative	One of:
body.cancel_at	JSON	Optional	A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period.
body.cancel_at (anyOf 1)	integer	Alternative	Format: unix-time
body.cancel_at (anyOf 2)	string	Alternative	One of: max_billed_until, max_period_end, min_period_end
body.cancel_at_period_end	boolean	Optional	Indicate whether this subscription should cancel at the end of the current period (`current_period_end`). Defaults to `false`.
body.collection_method	string	Optional	Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`. One of: charge_automatically, send_invoice
body.currency	string	Optional	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
body.days_until_due	integer	Optional	Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`.
body.default_payment_method	string	Optional	ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer’s [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source). Maximum length: 5000
body.default_source	string	Optional	ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer’s [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://docs.stripe.com/api/customers/object#customer_object-default_source). Maximum length: 5000
body.default_tax_rates	JSON	Optional	The tax rates that will apply to any subscription item that does not have `tax_rates` set. Invoices created will have their `default_tax_rates` populated from the subscription.
body.default_tax_rates (anyOf 1)	array	Alternative
body.default_tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
body.default_tax_rates (anyOf 2)	string	Alternative	One of:
body.discounts	JSON	Optional	The coupons to redeem into discounts for the subscription. If not specified or empty, inherits the discount from the subscription’s customer.
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.invoice_settings	Model	Optional	Expand Create a subscription — subscriptions post Subscriptions — request body — body invoice settings
body.items	array	Optional	A list of up to 20 subscription items, each with an attached price.
body.items[]	Model	Each item	Expand Create a subscription — subscriptions post Subscriptions — request body — body items item
body.metadata	JSON	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`.
body.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.metadata (anyOf 1).*	string	Additional keys
body.metadata (anyOf 2)	string	Alternative	One of:
body.off_session	boolean	Optional	Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session).
body.payment_behavior	string	Optional	Controls how Stripe handles the first invoice when payment is required and `collection_method=charge_automatically`. Subscriptions with `collection_method=send_invoice` are automatically activated regardless of the first Invoice status. One of: allow_incomplete, default_incomplete, error_if_incomplete, pending_if_incomplete
body.payment_settings	Model	Optional	Expand Update a subscription — request body — body payment settings
body.pending_invoice_item_interval	JSON	Optional	Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling [Create an invoice](/api/invoices/create) for the given subscription at the specified interval.
body.pending_invoice_item_interval (anyOf 1)	object	Alternative
body.pending_invoice_item_interval (anyOf 1).interval	string	Required within parent	One of: day, month, week, year
body.pending_invoice_item_interval (anyOf 1).interval_count	integer	Optional
body.pending_invoice_item_interval (anyOf 2)	string	Alternative	One of:
body.proration_behavior	string	Optional	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) resulting from the `billing_cycle_anchor`. If no value is passed, the default is `create_prorations`. One of: always_invoice, create_prorations, none
body.transfer_data	object	Optional	If specified, the funds from the subscription’s invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.
body.transfer_data.amount_percent	number	Optional
body.transfer_data.destination	string	Required within parent
body.trial_end	JSON	Optional	Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value `now` can be provided to end the customer’s trial immediately. Can be at most two years from `billing_cycle_anchor`. See [Using trial periods on subscriptions](https://docs.stripe.com/billing/subscriptions/trials/free-trials) to learn more.
body.trial_end (anyOf 1)	string	Alternative	One of: now Maximum length: 5000
body.trial_end (anyOf 2)	integer	Alternative	Format: unix-time
body.trial_from_plan	boolean	Optional	Indicates if a plan’s `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://docs.stripe.com/billing/subscriptions/trials/free-trials) to learn more.
body.trial_period_days	integer	Optional	Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See [Using trial periods on subscriptions](https://docs.stripe.com/billing/subscriptions/trials/free-trials) to learn more.
body.trial_settings	object	Optional	Settings related to subscription trials.
body.trial_settings.end_behavior	object	Required within parent
body.trial_settings.end_behavior.billing_cycle_anchor	string	Optional	One of: now, unchanged
body.trial_settings.end_behavior.missing_payment_method	string	Optional	One of: cancel, create_invoice, pause

Referenced models: Update a subscription — request body — body add invoice items item, Create a subscription — subscriptions post Subscriptions — request body — body invoice settings, Create a subscription — subscriptions post Subscriptions — request body — body items item, Update a subscription — request body — body payment settings

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 Pause a subscription — response body

Referenced models: Pause a subscription — response body

Schemas

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

Update a subscription — request body — body add invoice items item

Field	Type	Presence	Description and constraints
$	object	Root
discountable	boolean	Optional
discounts	array	Optional
discounts[]	object	Each item
discounts[].coupon	string	Optional	Maximum length: 5000
discounts[].discount	string	Optional	Maximum length: 5000
discounts[].promotion_code	string	Optional	Maximum length: 5000
metadata	object	Optional	Additional keys: see wildcard field
metadata.*	string	Additional keys
period	object	Optional
period.end	object	Required within parent
period.end.timestamp	integer	Optional	Format: unix-time
period.end.type	string	Required within parent	One of: min_item_period_end, timestamp
period.start	object	Required within parent
period.start.timestamp	integer	Optional	Format: unix-time
period.start.type	string	Required within parent	One of: max_item_period_start, now, timestamp
price	string	Optional	Maximum length: 5000
price_data	object	Optional
price_data.currency	string	Required within parent	Format: currency
price_data.product	string	Required within parent	Maximum length: 5000
price_data.tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
price_data.unit_amount	integer	Optional
price_data.unit_amount_decimal	string	Optional	Format: decimal
quantity	integer	Optional
tax_rates	JSON	Optional
tax_rates (anyOf 1)	array	Alternative
tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
tax_rates (anyOf 2)	string	Alternative	One of:

Create a subscription — subscriptions post Subscriptions — request body — body invoice settings

Field	Type	Presence	Description and constraints
$	object	Root	All invoices will be billed using the specified settings.
account_tax_ids	JSON	Optional
account_tax_ids (anyOf 1)	array	Alternative
account_tax_ids (anyOf 1)[]	string	Each item	Maximum length: 5000
account_tax_ids (anyOf 2)	string	Alternative	One of:
custom_fields	JSON	Optional
custom_fields (anyOf 1)	array	Alternative
custom_fields (anyOf 1)[]	object	Each item
custom_fields (anyOf 1)[].name	string	Required within parent	Maximum length: 40
custom_fields (anyOf 1)[].value	string	Required within parent	Maximum length: 140
custom_fields (anyOf 2)	string	Alternative	One of:
description	string	Optional	Maximum length: 1500
footer	string	Optional	Maximum length: 5000
issuer	object	Optional
issuer.account	string	Optional
issuer.type	string	Required within parent	One of: account, self

Create a subscription — subscriptions post Subscriptions — request body — body items item

Field	Type	Presence	Description and constraints
$	object	Root
billing_thresholds	JSON	Optional
billing_thresholds (anyOf 1)	object	Alternative
billing_thresholds (anyOf 1).usage_gte	integer	Required within parent
billing_thresholds (anyOf 2)	string	Alternative	One of:
current_trial	object	Optional
current_trial.trial_offer	string	Required within parent	Maximum length: 5000
discounts	JSON	Optional
discounts (anyOf 1)	array	Alternative
discounts (anyOf 1)[]	object	Each item
discounts (anyOf 1)[].coupon	string	Optional	Maximum length: 5000
discounts (anyOf 1)[].discount	string	Optional	Maximum length: 5000
discounts (anyOf 1)[].promotion_code	string	Optional	Maximum length: 5000
discounts (anyOf 2)	string	Alternative	One of:
metadata	object	Optional	Additional keys: see wildcard field
metadata.*	string	Additional keys
price	string	Optional	Maximum length: 5000
price_data	Model	Optional	Expand Update a subscription — request body — body items item price data
quantity	integer	Optional
tax_rates	JSON	Optional
tax_rates (anyOf 1)	array	Alternative
tax_rates (anyOf 1)[]	string	Each item	Maximum length: 5000
tax_rates (anyOf 2)	string	Alternative	One of:

Referenced models: Update a subscription — request body — body items item price data

Update a subscription — request body — body payment settings

Field	Type	Presence	Description and constraints
$	object	Root	Payment settings to pass to invoices created by the subscription.
payment_method_options	Model	Optional	Expand Update a subscription — request body — body payment settings payment method options
payment_method_types	JSON	Optional
payment_method_types (anyOf 1)	array	Alternative
payment_method_types (anyOf 1)[]	string	Each item	One of: ach_credit_transfer, ach_debit, acss_debit, affirm, alipay, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, blik, boleto, card, cashapp, crypto, custom, customer_balance, eps, fpx, giropay, grabpay, ideal, jp_credit_transfer, kakao_pay, klarna, konbini, kr_card, link, mb_way, multibanco, naver_pay, nz_bank_account, p24, pay_by_bank, payco, paynow, paypal, payto, pix, promptpay, revolut_pay, satispay, sepa_credit_transfer, sepa_debit, sofort, swish, twint, upi, us_bank_account, wechat_pay
payment_method_types (anyOf 2)	string	Alternative	One of:
save_default_payment_method	string	Optional	One of: off, on_subscription

Referenced models: Update a subscription — request body — body payment settings payment method options

PostApplicationFeesIdRefund — response body — application / object: application

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (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: application

Pause a subscription — response body — cancellation details Details about why this subscription was cancelled comment, feedback, feedback option, reason

Field	Type	Presence	Description and constraints
$	object	Root
comment	JSON	Optional
comment (anyOf 1)	string	Alternative	Additional comments about why the user canceled the subscription, if the subscription was canceled explicitly by the user. Maximum length: 5000
comment (anyOf 2)	null	Alternative
feedback	JSON	Optional
feedback (anyOf 1)	string	Alternative	The customer submitted reason for why they canceled, if the subscription was canceled explicitly by the user. Known values: customer_service, low_quality, missing_features, other, switched_service, too_complex, too_expensive, unused
feedback (anyOf 2)	null	Alternative
feedback_option	JSON	Optional
feedback_option (anyOf 1)	JSON	Alternative	Customized feedback options that provide deeper insight into why the subscription was canceled, if the subscription was canceled explicitly by the user.
feedback_option (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
feedback_option (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a feedback option — response body
feedback_option (anyOf 2)	null	Alternative
reason	JSON	Optional
reason (anyOf 1)	string	Alternative	Why this subscription was canceled. Known values: canceled_by_retention_policy, cancellation_requested, payment_disputed, payment_failed
reason (anyOf 2)	null	Alternative

Referenced models: Create a feedback option — response body

Accept a quote — response body — application / value / deleted: True, object: application

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (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: application

Cancel a Setup Intent — response body — managed payments value enabled

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	Set to `true` to enable [Managed Payments](https://docs.stripe.com/payments/managed-payments), Stripe's merchant of record solution, for this session.

Policy, approvals and errors

SDK function policy ID: stripe.postcustomerscustomersubscriptions. Catalog operation: PostCustomersCustomerSubscriptions. 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