@usethrottle/cart 3.10.1 → 3.11.0

package/README.md

@@ -222,23 +222,45 @@ await client.shippingTax.pushExternalSnapshot({
 
 ## Subscriptions
 
-Mark a line item with `type: 'subscription'`:
+Put `recurring` on a line to make it a subscription. A cart can hold any
+number of one-time lines and up to 10 subscription lines, with the same plan
+or different ones. The whole cart is paid in one capture, with one shipping
+fee, and completes as one order linked to every subscription it created.
 
 ```ts
+await client.items.add(cart.id, { name: 'Coffee kit', unitPrice: 4500, quantity: 1 });
 await client.items.add(cart.id, {
-  type: 'subscription',
-  name: 'Pro Plan',
-  unitPrice: 1900,
-  quantity: 1,
+  name: 'Barista Club',
+  unitPrice: 2000,          // per period, per seat
+  quantity: 2,              // seats
+  recurring: { plan: 'club_monthly', interval: 'monthly', trialDays: 14 },
 });
 ```
 
-Then call `client.carts.checkout` as normal.
-
-The billing schedule is **not** settable through this endpoint. The add-item
-body is strict and has no `recurring` field, so sending one is rejected with
-`Unsupported field(s): recurring` — the recurring plan is attached by the
-subscription engine, not by the cart API.
+- `interval` (`weekly`, `biweekly`, `monthly`, `quarterly`, `yearly`), or
+  `intervalUnit` (`hour`, `day`, `week`, `month`) + `intervalCount`: 1 hour
+  to 1 year.
+- `totalPayments` (2–60) makes an installment plan; `trialDays` (0–365) a free
+  trial. They cannot be combined (`400 invalid_combination`).
+- `type` is forced to `subscription`, and the line never ships:
+  `requiresShipping: true` is rejected with `400 validation_error`.
+- A free-trial line is stored with `unitPrice: 0` and your price on
+  `recurring.amount`, and its name gets a "— 14-day free trial" suffix.
+- `PATCH` may change `quantity` (seats) and `metadata` only. Changing
+  `unitPrice`, `taxAmount` or `discountAmount` is `422 recurring_line_immutable`.
+  Remove the line and add it again to change its terms.
+- Each line's `subscriptionId` is set when the checkout completes.
+
+| Status | Code | When |
+|---|---|---|
+| 422 | `too_many_subscriptions` | An 11th subscription line |
+| 422 | `recurring_not_supported_for_cart` | The cart is managed by an external cart provider |
+| 422 | `recurring_line_immutable` | A PATCH changes a subscription line's price, tax or discount |
+| 400 | `invalid_line_item` | A free-trial line carries `taxAmount` or `discountAmount` |
+| 400 | `invalid_interval` / `interval_conflict` / `invalid_total_payments` / `invalid_combination` / `invalid_plan` / `invalid_trial_days` | Terms out of range |
+
+Do not also send a session `recurring` intent for the same cart. The two are
+exclusive, and session creation answers `422 recurring_source_conflict`.
 
 ## Events
 

package/dist/index.d.cts

@@ -79,6 +79,47 @@ interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
      */
     unitCount: number;
 }
+type SubscriptionInterval = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
+type SubscriptionIntervalUnit = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Terms that make a cart line a subscription. One subscription is created per
+ * line when the checkout completes, with `quantity` as seats; at most 10 per
+ * cart. Send `interval`, or `intervalUnit` + `intervalCount` (1 hour to 1
+ * year). `totalPayments` (2-60) makes an installment plan; `trialDays`
+ * (0-365) a free trial, not combinable with `totalPayments`. The line's
+ * `unitPrice` is the per-period price per seat.
+ */
+interface LineRecurringInput {
+    plan: string;
+    planName?: string;
+    interval?: SubscriptionInterval;
+    intervalUnit?: SubscriptionIntervalUnit;
+    intervalCount?: number;
+    totalPayments?: number;
+    trialDays?: number;
+}
+/** A merchant-declared subscription line's stored terms (it carries `plan`). */
+interface StoredLineRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    totalPayments: number | null;
+    trialDays: number;
+    /** Renewal price per seat. Set only on a free-trial line, whose `unitPrice` is 0. */
+    amount: number | null;
+    /** Display mirror of `totalPayments`. */
+    count: number | null;
+}
+/** The plan line Throttle adds for a checkout session `recurring` intent. */
+interface LegacyLineRecurring {
+    interval: string;
+    intervalUnit?: string | null;
+    intervalCount?: number | null;
+    /** Display metadata: the number of payments to show. Not enforced. */
+    count: number | null;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -93,16 +134,13 @@ interface LineItem {
     discountAmount: number;
     total: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Subscription terms. `'plan' in recurring` tells a merchant-declared
+     * subscription line (`StoredLineRecurring`) from the plan line a checkout
+     * session adds (`LegacyLineRecurring`). Null on a one-time line.
      */
-    recurring: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring: StoredLineRecurring | LegacyLineRecurring | null;
+    /** The subscription this line created. Null until the checkout completes. */
+    subscriptionId: string | null;
     imageUrl: string | null;
     position: number;
     metadata: Record<string, unknown>;
@@ -181,16 +219,12 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Makes this line a subscription: `type` is forced to `subscription`, and it
+     * never ships (`requiresShipping: true` is rejected with it). A free-trial
+     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
+     * Terms cannot change later: remove the line and add it again.
      */
-    recurring?: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring?: LineRecurringInput;
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -201,6 +235,11 @@ interface AddLineItemInput {
     requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * On a subscription line only `quantity` (seats) and `metadata` may change;
+ * a different `unitPrice`, `taxAmount` or `discountAmount` is
+ * 422 `recurring_line_immutable`.
+ */
 interface UpdateLineItemInput {
     quantity?: number;
     unitPrice?: number;
@@ -705,4 +744,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineRecurringInput, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/dist/index.d.ts

@@ -79,6 +79,47 @@ interface CartSessionCart extends Omit<Cart, 'workspaceId'> {
      */
     unitCount: number;
 }
+type SubscriptionInterval = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
+type SubscriptionIntervalUnit = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Terms that make a cart line a subscription. One subscription is created per
+ * line when the checkout completes, with `quantity` as seats; at most 10 per
+ * cart. Send `interval`, or `intervalUnit` + `intervalCount` (1 hour to 1
+ * year). `totalPayments` (2-60) makes an installment plan; `trialDays`
+ * (0-365) a free trial, not combinable with `totalPayments`. The line's
+ * `unitPrice` is the per-period price per seat.
+ */
+interface LineRecurringInput {
+    plan: string;
+    planName?: string;
+    interval?: SubscriptionInterval;
+    intervalUnit?: SubscriptionIntervalUnit;
+    intervalCount?: number;
+    totalPayments?: number;
+    trialDays?: number;
+}
+/** A merchant-declared subscription line's stored terms (it carries `plan`). */
+interface StoredLineRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    totalPayments: number | null;
+    trialDays: number;
+    /** Renewal price per seat. Set only on a free-trial line, whose `unitPrice` is 0. */
+    amount: number | null;
+    /** Display mirror of `totalPayments`. */
+    count: number | null;
+}
+/** The plan line Throttle adds for a checkout session `recurring` intent. */
+interface LegacyLineRecurring {
+    interval: string;
+    intervalUnit?: string | null;
+    intervalCount?: number | null;
+    /** Display metadata: the number of payments to show. Not enforced. */
+    count: number | null;
+}
 interface LineItem {
     id: string;
     cartId: string;
@@ -93,16 +134,13 @@ interface LineItem {
     discountAmount: number;
     total: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Subscription terms. `'plan' in recurring` tells a merchant-declared
+     * subscription line (`StoredLineRecurring`) from the plan line a checkout
+     * session adds (`LegacyLineRecurring`). Null on a one-time line.
      */
-    recurring: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring: StoredLineRecurring | LegacyLineRecurring | null;
+    /** The subscription this line created. Null until the checkout completes. */
+    subscriptionId: string | null;
     imageUrl: string | null;
     position: number;
     metadata: Record<string, unknown>;
@@ -181,16 +219,12 @@ interface AddLineItemInput {
     taxAmount?: number;
     discountAmount?: number;
     /**
-     * Display metadata. `count` is the number of payments to show, and is not
-     * enforced. On the plan line Throttle writes for a recurring checkout,
-     * `intervalUnit`/`intervalCount` describe a custom cadence.
+     * Makes this line a subscription: `type` is forced to `subscription`, and it
+     * never ships (`requiresShipping: true` is rejected with it). A free-trial
+     * line is stored with `unitPrice` 0 and your price on `recurring.amount`.
+     * Terms cannot change later: remove the line and add it again.
      */
-    recurring?: {
-        interval: string;
-        count: number | null;
-        intervalUnit?: string | null;
-        intervalCount?: number | null;
-    } | null;
+    recurring?: LineRecurringInput;
     imageUrl?: string;
     /**
      * Whether this item is physically shippable. For external/ad-hoc catalogs
@@ -201,6 +235,11 @@ interface AddLineItemInput {
     requiresShipping?: boolean;
     metadata?: Record<string, unknown>;
 }
+/**
+ * On a subscription line only `quantity` (seats) and `metadata` may change;
+ * a different `unitPrice`, `taxAmount` or `discountAmount` is
+ * 422 `recurring_line_immutable`.
+ */
 interface UpdateLineItemInput {
     quantity?: number;
     unitPrice?: number;
@@ -705,4 +744,4 @@ declare function cartErrorFromResponse(args: {
     responseHeaders?: ThrottleErrorArgs['responseHeaders'];
 }): ThrottleApiError;
 
-export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LineItem, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, StorefrontQuoteClient, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };
+export { type AddLineItemInput, type AppliedDiscount, type Cart, type CartAddress, type CartBranding, CartClient, type CartEvent, CartNotFoundError, CartNotOpenError, type CartSession, type CartSessionCart, CartSessionClient, type CartSessionClientOptions, type CartSessionSummary, CartTimeoutError, type CheckoutHandoff, type CheckoutHandoffInput, type CheckoutInput, type CreateCartInput, type CreateCartSessionInput, type ExternalShippingTaxSnapshotInput, type LegacyLineRecurring, type LineItem, type LineRecurringInput, type Order, type SelectShippingInput, type SelectedShipping, type ShippingTaxAddress, type ShippingTaxCalculationResponse, type ShippingTaxCartCalculateInput, type ShippingTaxMethod, type ShippingTaxQuoteInput, type ShippingTaxQuoteItem, type StoredLineRecurring, StorefrontQuoteClient, type SubscriptionInterval, type SubscriptionIntervalUnit, type TaxLine, type TaxLineInput, ThrottleApiError, type UpdateCartInput, type UpdateCartSessionInput, type UpdateLineItemInput, cartErrorFromResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/cart",
-  "version": "3.10.1",
+  "version": "3.11.0",
   "description": "Typed REST client for the Throttle Cart API.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run",
+    "test": "tsc --noEmit --strict --skipLibCheck --target es2022 --lib es2022,dom --module esnext --moduleResolution bundler __tests__/recurring-types.check.ts && vitest run",
     "typecheck": "tsc --noEmit"
   }
 }