Stripe: Create a trial offer

← Product catalog operations · Get started

Operation stripe.postproductcatalogtrialoffers

Provider route: POST /v1/product_catalog/trial_offers. 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["productCatalog"]["postProductCatalogTrialOffers"]>[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.productCatalog.postProductCatalogTrialOffers(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.product_catalog.post_product_catalog_trial_offers(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.active	boolean	Optional	Whether the trial offer can be used for new subscriptions. Defaults to true.
body.duration	object	Required within parent	Duration of one service period of the trial.
body.duration.relative	object	Optional
body.duration.relative.iterations	integer	Required within parent
body.duration.type	string	Required within parent	One of: relative
body.end_behavior	object	Required within parent	Define behavior that occurs at the end of the trial.
body.end_behavior.transition	object	Required within parent
body.end_behavior.transition.price	string	Required within parent	Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.nickname	string	Optional	A brief description of the trial offer, hidden from customers. Maximum length: 255
body.price	string	Required within parent	Price configuration during the trial period (amount, billing scheme, etc). 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 trial offer — response body

Referenced models: Create a trial offer — response body

Schemas

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

Create a trial offer — response body

Field	Type	Presence	Description and constraints
$	object	Root	Trial offers let you define free or paid introductory pricing for a subscription item. A TrialOffer specifies the price to charge during the trial, how many billing intervals the trial lasts, and what price the subscription item transitions to when the trial ends. You attach a TrialOffer to a subscription item using `items[current_trial][trial_offer]` when creating or updating a subscription.
active	boolean	Required within parent	Whether the trial offer is active. Set to false to archive the trial offer.
duration	Model	Required within parent	Expand Create a trial offer — response body — duration
end_behavior	Model	Required within parent	Expand Create a trial offer — response body — end behavior
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
nickname	JSON	Optional
nickname (anyOf 1)	string	Alternative	A brief description of the trial offer, hidden from customers. Maximum length: 255
nickname (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: product_catalog.trial_offer
price	JSON	Required within parent	The price during the trial offer.
price (anyOf 1)	string	Alternative	Maximum length: 5000
price (anyOf 2)	Model	Alternative	Expand Create a price — response body
price (anyOf 3)	Model	Alternative	Expand Create a trial offer — response body — price / deleted: True, object: price

Referenced models: Create a trial offer — response body — price / deleted: True, object: price, Create a price — response body, Create a trial offer — response body — duration, Create a trial offer — response body — end behavior

Create a trial offer — response body — price / deleted: True, object: price

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
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: price

Create a trial offer — response body — duration

Field	Type	Presence	Description and constraints
$	object	Root
relative	Model	Optional	Expand Create a trial offer — response body — duration relative
type	string	Required within parent	The type of trial offer duration. Known values: relative

Referenced models: Create a trial offer — response body — duration relative

Create a trial offer — response body — end behavior

Field	Type	Presence	Description and constraints
$	object	Root
transition	Model	Optional	Expand Create a trial offer — response body — end behavior transition
type	string	Required within parent	The type of behavior when the trial offer ends. Known values: transition

Referenced models: Create a trial offer — response body — end behavior transition

Create a price — response body — currency options value

Field	Type	Presence	Description and constraints
$	object	Root
custom_unit_amount	JSON	Optional
custom_unit_amount (anyOf 1)	JSON	Alternative	When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links.
custom_unit_amount (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a price — response body — custom unit amount value maximum, minimum, preset
custom_unit_amount (anyOf 2)	null	Alternative
tax_behavior	JSON	Optional
tax_behavior (anyOf 1)	string	Alternative	Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. Known values: exclusive, inclusive, unspecified
tax_behavior (anyOf 2)	null	Alternative
tiers	array	Optional	Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`.
tiers[]	Model	Each item	Expand Create a plan — response body — tiers item
unit_amount	JSON	Optional
unit_amount (anyOf 1)	JSON	Alternative
unit_amount (anyOf 1) (anyOf 1)	integer	Alternative	The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`.
unit_amount (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
unit_amount (anyOf 2)	null	Alternative
unit_amount_decimal	JSON	Optional
unit_amount_decimal (anyOf 1)	string	Alternative	The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`. Format: decimal
unit_amount_decimal (anyOf 2)	null	Alternative

Referenced models: Create a price — response body — custom unit amount value maximum, minimum, preset, Create a plan — response body — tiers item

Create a price — response body — custom unit amount value maximum, minimum, preset

Field	Type	Presence	Description and constraints
$	object	Root
maximum	JSON	Optional
maximum (anyOf 1)	JSON	Alternative
maximum (anyOf 1) (anyOf 1)	integer	Alternative	The maximum unit amount the customer can specify for this item.
maximum (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
maximum (anyOf 2)	null	Alternative
minimum	JSON	Optional
minimum (anyOf 1)	JSON	Alternative
minimum (anyOf 1) (anyOf 1)	integer	Alternative	The minimum unit amount the customer can specify for this item. Must be at least the minimum charge amount.
minimum (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
minimum (anyOf 2)	null	Alternative
preset	JSON	Optional
preset (anyOf 1)	JSON	Alternative
preset (anyOf 1) (anyOf 1)	integer	Alternative	The starting unit amount which can be updated by the customer.
preset (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
preset (anyOf 2)	null	Alternative

Delete a product — response body

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
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: product

Create a price — response body — recurring / value / interval: day, month, week, year, usage type: licensed, metered

Field	Type	Presence	Description and constraints
$	object	Root
interval	string	Required within parent	The frequency at which a subscription is billed. One of `day`, `week`, `month` or `year`. Known values: day, month, week, year
interval_count	JSON	Required within parent
interval_count (anyOf 1)	integer	Alternative	The number of intervals (specified in the `interval` attribute) between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months.
interval_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
meter	JSON	Optional
meter (anyOf 1)	string	Alternative	The meter tracking the usage of a metered price Maximum length: 5000
meter (anyOf 2)	null	Alternative
usage_type	string	Required within parent	Configures how the quantity per period should be determined. Can be either `metered` or `licensed`. `licensed` automatically bills the `quantity` set when adding it to a subscription. `metered` aggregates the total usage based on usage records. Defaults to `licensed`. Known values: licensed, metered

Policy, approvals and errors

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