@usehercules/sdk 1.7.0 → 1.8.0

package/resources/beta/commerce/products/variants.d.mts

@@ -0,0 +1,798 @@
+import { APIResource } from "../../../../core/resource.mjs";
+import { APIPromise } from "../../../../core/api-promise.mjs";
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from "../../../../core/pagination.mjs";
+import { RequestOptions } from "../../../../internal/request-options.mjs";
+export declare class Variants extends APIResource {
+    /**
+     * Creates a new variant with pricing for a product. Use variants to offer multiple
+     * pricing tiers or configurations (e.g., Basic at $10/month, Pro at $25/month). A
+     * Stripe Price is automatically created.
+     */
+    create(productID: string, body: VariantCreateParams, options?: RequestOptions): APIPromise<VariantCreateResponse>;
+    /**
+     * Updates an existing variant. Use this to modify the name, description, or active
+     * status. Pricing cannot be changed after creation—create a new variant instead.
+     */
+    update(variantID: string, params: VariantUpdateParams, options?: RequestOptions): APIPromise<VariantUpdateResponse>;
+    /**
+     * Retrieves all variants for a product. Variants represent different pricing tiers
+     * or configurations (e.g., Basic, Pro, Enterprise) within a single product.
+     */
+    list(productID: string, query?: VariantListParams | null | undefined, options?: RequestOptions): PagePromise<VariantListResponsesCursorIDPage, VariantListResponse>;
+    /**
+     * Archives a variant, preventing new subscriptions. The associated Stripe Price is
+     * also archived. Existing subscriptions remain active.
+     */
+    archive(variantID: string, params: VariantArchiveParams, options?: RequestOptions): APIPromise<VariantArchiveResponse>;
+    /**
+     * Retrieves a variant by ID. Returns the variant object including pricing details
+     * and status.
+     */
+    get(variantID: string, params: VariantGetParams, options?: RequestOptions): APIPromise<VariantGetResponse>;
+}
+export type VariantListResponsesCursorIDPage = CursorIDPage<VariantListResponse>;
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface VariantCreateResponse {
+    /**
+     * Unique identifier for the topic subscription
+     */
+    id: string;
+    /**
+     * Whether the variant is available for new purchases
+     */
+    active: boolean;
+    /**
+     * Timestamp when the variant was created
+     */
+    created: string;
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    default_price?: VariantCreateResponse.DefaultPrice | null;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string | null;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantCreateResponse.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantCreateResponse.Recurring | null;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantCreateResponse {
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    interface DefaultPrice {
+        /**
+         * Unique identifier for the topic subscription
+         */
+        id: string;
+        /**
+         * How to handle the billing cycle when switching plans. 'now' resets to current
+         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
+         */
+        billing_cycle_anchor: 'now' | 'unchanged' | null;
+        /**
+         * Three-letter ISO currency code (e.g., usd, eur)
+         */
+        currency: string;
+        /**
+         * Billing frequency for recurring prices: day, week, month, or year. Null for
+         * one-time prices.
+         */
+        interval: 'day' | 'week' | 'month' | 'year' | null;
+        /**
+         * Number of intervals between billings for recurring prices. Null for one-time
+         * prices.
+         */
+        interval_count: number | null;
+        /**
+         * How to handle prorations when switching plans. 'default' creates prorations,
+         * 'none' disables them. Null for one-time prices.
+         */
+        proration_behavior: 'default' | 'none' | null;
+        /**
+         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
+         * billing period start. Null for one-time prices or to use Stripe's default.
+         */
+        proration_date: 'now' | 'start_of_period' | null;
+        /**
+         * Price type: one_time for single purchases, recurring for subscriptions
+         */
+        type: 'one_time' | 'recurring';
+        /**
+         * Price amount in the smallest currency unit (e.g., cents)
+         */
+        unit_amount: number | null;
+    }
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface VariantUpdateResponse {
+    /**
+     * Unique identifier for the topic subscription
+     */
+    id: string;
+    /**
+     * Whether the variant is available for new purchases
+     */
+    active: boolean;
+    /**
+     * Timestamp when the variant was created
+     */
+    created: string;
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    default_price?: VariantUpdateResponse.DefaultPrice | null;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string | null;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantUpdateResponse.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantUpdateResponse.Recurring | null;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantUpdateResponse {
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    interface DefaultPrice {
+        /**
+         * Unique identifier for the topic subscription
+         */
+        id: string;
+        /**
+         * How to handle the billing cycle when switching plans. 'now' resets to current
+         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
+         */
+        billing_cycle_anchor: 'now' | 'unchanged' | null;
+        /**
+         * Three-letter ISO currency code (e.g., usd, eur)
+         */
+        currency: string;
+        /**
+         * Billing frequency for recurring prices: day, week, month, or year. Null for
+         * one-time prices.
+         */
+        interval: 'day' | 'week' | 'month' | 'year' | null;
+        /**
+         * Number of intervals between billings for recurring prices. Null for one-time
+         * prices.
+         */
+        interval_count: number | null;
+        /**
+         * How to handle prorations when switching plans. 'default' creates prorations,
+         * 'none' disables them. Null for one-time prices.
+         */
+        proration_behavior: 'default' | 'none' | null;
+        /**
+         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
+         * billing period start. Null for one-time prices or to use Stripe's default.
+         */
+        proration_date: 'now' | 'start_of_period' | null;
+        /**
+         * Price type: one_time for single purchases, recurring for subscriptions
+         */
+        type: 'one_time' | 'recurring';
+        /**
+         * Price amount in the smallest currency unit (e.g., cents)
+         */
+        unit_amount: number | null;
+    }
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface VariantListResponse {
+    /**
+     * Unique identifier for the topic subscription
+     */
+    id: string;
+    /**
+     * Whether the variant is available for new purchases
+     */
+    active: boolean;
+    /**
+     * Timestamp when the variant was created
+     */
+    created: string;
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    default_price?: VariantListResponse.DefaultPrice | null;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string | null;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantListResponse.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantListResponse.Recurring | null;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantListResponse {
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    interface DefaultPrice {
+        /**
+         * Unique identifier for the topic subscription
+         */
+        id: string;
+        /**
+         * How to handle the billing cycle when switching plans. 'now' resets to current
+         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
+         */
+        billing_cycle_anchor: 'now' | 'unchanged' | null;
+        /**
+         * Three-letter ISO currency code (e.g., usd, eur)
+         */
+        currency: string;
+        /**
+         * Billing frequency for recurring prices: day, week, month, or year. Null for
+         * one-time prices.
+         */
+        interval: 'day' | 'week' | 'month' | 'year' | null;
+        /**
+         * Number of intervals between billings for recurring prices. Null for one-time
+         * prices.
+         */
+        interval_count: number | null;
+        /**
+         * How to handle prorations when switching plans. 'default' creates prorations,
+         * 'none' disables them. Null for one-time prices.
+         */
+        proration_behavior: 'default' | 'none' | null;
+        /**
+         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
+         * billing period start. Null for one-time prices or to use Stripe's default.
+         */
+        proration_date: 'now' | 'start_of_period' | null;
+        /**
+         * Price type: one_time for single purchases, recurring for subscriptions
+         */
+        type: 'one_time' | 'recurring';
+        /**
+         * Price amount in the smallest currency unit (e.g., cents)
+         */
+        unit_amount: number | null;
+    }
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface VariantArchiveResponse {
+    /**
+     * Unique identifier for the topic subscription
+     */
+    id: string;
+    /**
+     * Whether the variant is available for new purchases
+     */
+    active: boolean;
+    /**
+     * Timestamp when the variant was created
+     */
+    created: string;
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    default_price?: VariantArchiveResponse.DefaultPrice | null;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string | null;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantArchiveResponse.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantArchiveResponse.Recurring | null;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantArchiveResponse {
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    interface DefaultPrice {
+        /**
+         * Unique identifier for the topic subscription
+         */
+        id: string;
+        /**
+         * How to handle the billing cycle when switching plans. 'now' resets to current
+         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
+         */
+        billing_cycle_anchor: 'now' | 'unchanged' | null;
+        /**
+         * Three-letter ISO currency code (e.g., usd, eur)
+         */
+        currency: string;
+        /**
+         * Billing frequency for recurring prices: day, week, month, or year. Null for
+         * one-time prices.
+         */
+        interval: 'day' | 'week' | 'month' | 'year' | null;
+        /**
+         * Number of intervals between billings for recurring prices. Null for one-time
+         * prices.
+         */
+        interval_count: number | null;
+        /**
+         * How to handle prorations when switching plans. 'default' creates prorations,
+         * 'none' disables them. Null for one-time prices.
+         */
+        proration_behavior: 'default' | 'none' | null;
+        /**
+         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
+         * billing period start. Null for one-time prices or to use Stripe's default.
+         */
+        proration_date: 'now' | 'start_of_period' | null;
+        /**
+         * Price type: one_time for single purchases, recurring for subscriptions
+         */
+        type: 'one_time' | 'recurring';
+        /**
+         * Price amount in the smallest currency unit (e.g., cents)
+         */
+        unit_amount: number | null;
+    }
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface VariantGetResponse {
+    /**
+     * Unique identifier for the topic subscription
+     */
+    id: string;
+    /**
+     * Whether the variant is available for new purchases
+     */
+    active: boolean;
+    /**
+     * Timestamp when the variant was created
+     */
+    created: string;
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    default_price?: VariantGetResponse.DefaultPrice | null;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string | null;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantGetResponse.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantGetResponse.Recurring | null;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantGetResponse {
+    /**
+     * Price configuration for a product. Can be one-time or recurring (subscription).
+     */
+    interface DefaultPrice {
+        /**
+         * Unique identifier for the topic subscription
+         */
+        id: string;
+        /**
+         * How to handle the billing cycle when switching plans. 'now' resets to current
+         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
+         */
+        billing_cycle_anchor: 'now' | 'unchanged' | null;
+        /**
+         * Three-letter ISO currency code (e.g., usd, eur)
+         */
+        currency: string;
+        /**
+         * Billing frequency for recurring prices: day, week, month, or year. Null for
+         * one-time prices.
+         */
+        interval: 'day' | 'week' | 'month' | 'year' | null;
+        /**
+         * Number of intervals between billings for recurring prices. Null for one-time
+         * prices.
+         */
+        interval_count: number | null;
+        /**
+         * How to handle prorations when switching plans. 'default' creates prorations,
+         * 'none' disables them. Null for one-time prices.
+         */
+        proration_behavior: 'default' | 'none' | null;
+        /**
+         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
+         * billing period start. Null for one-time prices or to use Stripe's default.
+         */
+        proration_date: 'now' | 'start_of_period' | null;
+        /**
+         * Price type: one_time for single purchases, recurring for subscriptions
+         */
+        type: 'one_time' | 'recurring';
+        /**
+         * Price amount in the smallest currency unit (e.g., cents)
+         */
+        unit_amount: number | null;
+    }
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+export interface VariantCreateParams {
+    /**
+     * Display name for the variant (e.g., Basic, Standard, Premium)
+     */
+    name: string;
+    /**
+     * Optional custom ID for the variant. If not provided, one will be generated.
+     */
+    id?: string;
+    /**
+     * Three-letter ISO currency code
+     */
+    currency?: string;
+    /**
+     * Detailed description of what this variant includes
+     */
+    description?: string;
+    /**
+     * Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantCreateParams.Media>;
+    /**
+     * Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    recurring?: VariantCreateParams.Recurring;
+    /**
+     * Price amount in the smallest currency unit (e.g., cents). Use 0 for free
+     * variants.
+     */
+    unit_amount?: number;
+}
+export declare namespace VariantCreateParams {
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+    /**
+     * Recurring billing configuration for subscription variants
+     */
+    interface Recurring {
+        /**
+         * Billing frequency: day, week, month, or year
+         */
+        interval: 'day' | 'week' | 'month' | 'year';
+        /**
+         * Number of intervals between billings
+         */
+        interval_count?: number;
+    }
+}
+export interface VariantUpdateParams {
+    /**
+     * Path param: The unique identifier of the product
+     */
+    product_id: string;
+    /**
+     * Body param: Whether the variant is available for new purchases
+     */
+    active?: boolean;
+    /**
+     * Body param: Detailed description of what this variant includes
+     */
+    description?: string;
+    /**
+     * Body param: Media attachments (images, videos) for the variant
+     */
+    media?: Array<VariantUpdateParams.Media>;
+    /**
+     * Body param: Custom metadata for the variant
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Body param: Display name for the variant
+     */
+    name?: string;
+}
+export declare namespace VariantUpdateParams {
+    /**
+     * Media attachment for products or variants
+     */
+    interface Media {
+        /**
+         * Type of media: image, video, or external link
+         */
+        type: 'image' | 'video' | 'external';
+        /**
+         * URL of the media resource
+         */
+        url: string;
+    }
+}
+export interface VariantListParams extends CursorIDPageParams {
+    /**
+     * Filter by active status
+     */
+    active?: 'true' | 'false';
+}
+export interface VariantArchiveParams {
+    /**
+     * The unique identifier of the product
+     */
+    product_id: string;
+}
+export interface VariantGetParams {
+    /**
+     * The unique identifier of the product
+     */
+    product_id: string;
+}
+export declare namespace Variants {
+    export { type VariantCreateResponse as VariantCreateResponse, type VariantUpdateResponse as VariantUpdateResponse, type VariantListResponse as VariantListResponse, type VariantArchiveResponse as VariantArchiveResponse, type VariantGetResponse as VariantGetResponse, type VariantListResponsesCursorIDPage as VariantListResponsesCursorIDPage, type VariantCreateParams as VariantCreateParams, type VariantUpdateParams as VariantUpdateParams, type VariantListParams as VariantListParams, type VariantArchiveParams as VariantArchiveParams, type VariantGetParams as VariantGetParams, };
+}
+//# sourceMappingURL=variants.d.mts.map