Stripe.Product reference

Coupon

Source: src/Stripe/Coupon.ts

A Stripe Coupon — a percent-off or amount-off discount applied to subscriptions, invoices, Checkout sessions, and quotes. Coupons do not apply to one-off charges or PaymentIntents.

Create with either percentOff or amountOff + currency. duration is forever, once (the default), or repeating (requires durationInMonths). Name, metadata, and currencyOptions update in place; the discount shape is immutable and changing it replaces the coupon.

Coupon: Creating a Coupon

Percent-off forever

const welcome = yield* Stripe.Coupon("welcome", {
  percentOff: 20,
  duration: "forever",
  name: "Welcome 20%",
});

Amount-off once

const fiveOff = yield* Stripe.Coupon("five-off", {
  amountOff: 500,
  currency: "usd",
  duration: "once",
  name: "$5 off",
});

Coupon: Repeating duration

const quarterly = yield* Stripe.Coupon("quarterly", {
  percentOff: 10,
  duration: "repeating",
  durationInMonths: 3,
});

Coupon: Updating a Coupon

const welcome = yield* Stripe.Coupon("welcome", {
  percentOff: 20,
  duration: "forever",
  name: "Welcome 20% (updated)",
  metadata: { campaign: "spring" },
});

Plan

Source: src/Stripe/Plan.ts

A Stripe Plan — the legacy (pre-Price) catalog object that defines currency, amount, and billing interval for a Product. Prefer Price for new catalogs; Plan exists for the Plans API.

Currency, amount, interval, usage type, and billing scheme are immutable (changing them replaces the plan). Nickname, metadata, active, trialPeriodDays, and product update in place. Destroy hard-deletes the plan; existing subscribers are not affected.

Plan: Creating a Plan

Monthly plan

const product = yield* Stripe.Product("pro-plan", { name: "Pro Plan" });
const plan = yield* Stripe.Plan("pro-monthly", {
  product: product.id,
  currency: "usd",
  interval: "month",
  amount: 1500,
  nickname: "Pro monthly",
});

Yearly plan

const plan = yield* Stripe.Plan("pro-yearly", {
  product: product.id,
  currency: "usd",
  interval: "year",
  amount: 15000,
  nickname: "Pro yearly",
});

Plan: Updating a Plan

const plan = yield* Stripe.Plan("pro-monthly", {
  product: product.id,
  currency: "usd",
  interval: "month",
  amount: 1500,
  nickname: "Pro monthly (paused)",
  trialPeriodDays: 14,
  metadata: { tier: "pro" },
});

Price

Source: src/Stripe/Price.ts

A Stripe Price — the unit cost attached to a Product. Currency, amount, product, and recurring interval are immutable (changing them replaces the price). Nickname, metadata, lookup key, and active update in place. Prices cannot be deleted; destroy deactivates them (active=false).

Price: Creating a Price

One-time price

const product = yield* Stripe.Product("pro-plan", { name: "Pro Plan" });
const price = yield* Stripe.Price("pro-once", {
  product,
  currency: "usd",
  unitAmount: 2000,
});

Recurring monthly price

const price = yield* Stripe.Price("pro-monthly", {
  product,
  currency: "usd",
  unitAmount: 1500,
  recurring: { interval: "month" },
  nickname: "Pro monthly",
});

Price: Updating a Price

const price = yield* Stripe.Price("pro-monthly", {
  product,
  currency: "usd",
  unitAmount: 1500,
  recurring: { interval: "month" },
  nickname: "Pro monthly (paused)",
  active: false,
  metadata: { tier: "pro" },
});

Price: Destroying a Price

// Stripe cannot delete a used price. `alchemy destroy` sets
// `active: false`.

Product

Source: src/Stripe/Product.ts

A Stripe Product — the catalog item that Prices, invoices, and Checkout attach to. Name, description, active, images, and metadata are updated in place. Deleting a product is only possible when it has no Prices.

Product: Creating a Product

Generated name

const product = yield* Stripe.Product("pro-plan");

Named product with description

const product = yield* Stripe.Product("pro-plan", {
  name: "Pro Plan",
  description: "Billed monthly",
});

Product: Catalog details

const product = yield* Stripe.Product("pro-plan", {
  name: "Pro Plan",
  description: "Billed monthly",
  active: false,
  images: ["https://example.com/pro.png"],
  metadata: { tier: "pro" },
});

Product: Destroying a Product

// alchemy destroy deletes the Product. If prices remain, Stripe
// rejects the delete and Alchemy archives it (`active: false`).

ProductFeature

Source: src/Stripe/ProductFeature.ts

A Stripe Product Feature — the attachment of an Entitlements Feature to a Product. When a customer purchases a product that has a feature attached, Stripe creates an entitlement to that feature. Existence-only: there is nothing to update in place; changing product or entitlementFeature replaces the attachment. Destroy deletes it.

Product features have no metadata of their own. Ownership for account-wide list() (nuke) is inferred from the parent Product’s Alchemy metadata.

ProductFeature: Attaching a Feature

const product = yield* Stripe.Product("pro-plan", { name: "Pro Plan" });
const analytics = yield* Stripe.EntitlementsFeature("analytics", {
  lookupKey: "analytics",
  name: "Analytics",
});
const attachment = yield* Stripe.ProductFeature("pro-analytics", {
  product: product.id,
  entitlementFeature: analytics.id,
});

ProductFeature: Replacing an Attachment

const reporting = yield* Stripe.EntitlementsFeature("reporting", {
  lookupKey: "reporting",
  name: "Reporting",
});
const attachment = yield* Stripe.ProductFeature("pro-analytics", {
  product: product.id,
  entitlementFeature: reporting.id,
});

PromotionCode

Source: src/Stripe/PromotionCode.ts

A Stripe Promotion Code — a customer-redeemable code for an underlying coupon. Stripe does not hard-delete promotion codes; destroying this resource deactivates it (active: false).

code, coupon, customer, expiresAt, maxRedemptions, and most restrictions are immutable. Changing them replaces the promotion code (create a new one, then deactivate the old). active, metadata, and restrictions.currencyOptions update in place.

PromotionCode: Creating a Promotion Code

Code for an existing coupon

const welcome = yield* Stripe.PromotionCode("welcome", {
  coupon: "25OFF",
  code: "WELCOME25",
});

Generated code with a redemption cap

const launch = yield* Stripe.PromotionCode("launch", {
  coupon: "10OFF",
  maxRedemptions: 100,
  metadata: { campaign: "launch" },
});

PromotionCode: Updating a Promotion Code

const welcome = yield* Stripe.PromotionCode("welcome", {
  coupon: "25OFF",
  code: "WELCOME25",
  active: false,
  metadata: { campaign: "paused" },
});

PromotionCode: Deactivating a Promotion Code

// stack.destroy() / resource removal sets active: false
const welcome = yield* Stripe.PromotionCode("welcome", {
  coupon: "25OFF",
  code: "WELCOME25",
});

RetrieveCoupon

Source: src/Stripe/RetrieveCoupon.ts

Retrieve a bound Stripe Coupon over HTTP.

RetrieveCoupon: Reading a Coupon

const retrieve = yield* Stripe.RetrieveCoupon(coupon);
const live = yield* retrieve();

RetrieveCouponHttp

Source: src/Stripe/RetrieveCouponHttp.ts Kind: Layer · Provides: Stripe.RetrieveCoupon

HTTP implementation of RetrieveCoupon. Provide it on the Function or Worker Effect.

RetrievePlan

Source: src/Stripe/RetrievePlan.ts

Retrieve a bound Stripe Plan over HTTP.

RetrievePlan: Reading a Plan

const retrieve = yield* Stripe.RetrievePlan(plan);
const live = yield* retrieve();

RetrievePlanHttp

Source: src/Stripe/RetrievePlanHttp.ts Kind: Layer · Provides: Stripe.RetrievePlan

HTTP implementation of RetrievePlan. Provide it on the Function or Worker Effect.

RetrievePrice

Source: src/Stripe/RetrievePrice.ts

Retrieve a bound Stripe Price over HTTP.

RetrievePrice: Reading a Price

const retrieve = yield* Stripe.RetrievePrice(price);
const live = yield* retrieve();

RetrievePriceHttp

Source: src/Stripe/RetrievePriceHttp.ts Kind: Layer · Provides: Stripe.RetrievePrice

HTTP implementation of RetrievePrice. Provide it on the Function or Worker Effect.

RetrieveProduct

Source: src/Stripe/RetrieveProduct.ts

Retrieve a bound Stripe Product over HTTP. Pass the Product resource, a prod_… id string, or an Effect resolving to a Product.

RetrieveProduct: Reading a Product

Bind and retrieve

const retrieve = yield* Stripe.RetrieveProduct(product);
const live = yield* retrieve();

By id

const retrieve = yield* Stripe.RetrieveProduct("prod_123");
const live = yield* retrieve();

RetrieveProductFeature

Source: src/Stripe/RetrieveProductFeature.ts

Retrieve a bound Stripe Product Feature attachment over HTTP.

RetrieveProductFeature: Reading a Product Feature

const retrieve = yield* Stripe.RetrieveProductFeature(seatsOnPro);
const live = yield* retrieve();

RetrieveProductFeatureHttp

Source: src/Stripe/RetrieveProductFeatureHttp.ts Kind: Layer · Provides: Stripe.RetrieveProductFeature

HTTP implementation of RetrieveProductFeature. The list-item retrieve takes both product and id.

RetrieveProductHttp

Source: src/Stripe/RetrieveProductHttp.ts Kind: Layer · Provides: Stripe.RetrieveProduct

HTTP implementation of RetrieveProduct. Provide it on the Function or Worker Effect. Accepts a Product resource, a prod_… id string, or an Effect resolving to a Product.

RetrievePromotionCode

Source: src/Stripe/RetrievePromotionCode.ts

Retrieve a bound Stripe Promotion Code over HTTP.

RetrievePromotionCode: Reading a Promotion Code

const retrieve = yield* Stripe.RetrievePromotionCode(promo);
const live = yield* retrieve();

RetrievePromotionCodeHttp

Source: src/Stripe/RetrievePromotionCodeHttp.ts Kind: Layer · Provides: Stripe.RetrievePromotionCode

HTTP implementation of RetrievePromotionCode. Provide it on the Function or Worker Effect.

RetrieveShippingRate

Source: src/Stripe/RetrieveShippingRate.ts

Retrieve a bound Stripe Shipping Rate over HTTP.

RetrieveShippingRate: Reading a Shipping Rate

const retrieve = yield* Stripe.RetrieveShippingRate(ground);
const live = yield* retrieve();

RetrieveShippingRateHttp

Source: src/Stripe/RetrieveShippingRateHttp.ts Kind: Layer · Provides: Stripe.RetrieveShippingRate

HTTP implementation of RetrieveShippingRate. Provide it on the Function or Worker Effect.

ShippingRate

Source: src/Stripe/ShippingRate.ts

A Stripe Shipping Rate — the price of shipping presented to customers and applied to a purchase. Amount, currency, display name, delivery estimate, and tax code are immutable (changing them replaces the rate). active, metadata, taxBehavior, and per-currency currencyOptions update in place. Shipping rates cannot be deleted; destroy deactivates them (active=false).

ShippingRate: Creating a Shipping Rate

Fixed-amount USD rate

const ground = yield* Stripe.ShippingRate("ground", {
  displayName: "Ground",
  amount: 500,
  currency: "usd",
});

Rate with a delivery estimate

const express = yield* Stripe.ShippingRate("express", {
  displayName: "Express",
  amount: 1500,
  currency: "usd",
  deliveryEstimate: {
    minimum: { unit: "business_day", value: 1 },
    maximum: { unit: "business_day", value: 3 },
  },
});

ShippingRate: Updating a Shipping Rate

const ground = yield* Stripe.ShippingRate("ground", {
  displayName: "Ground",
  amount: 500,
  currency: "usd",
  active: false,
  metadata: { region: "us" },
});

ShippingRate: Deactivating a Shipping Rate

// stack.destroy() / resource removal sets active: false
const ground = yield* Stripe.ShippingRate("ground", {
  displayName: "Ground",
  amount: 500,
  currency: "usd",
});