// Subscriptions: recurring payments. import { collect, request, segment } from "./stripe" import type { Client, Page, RequestOptions, SearchPage, StripeError } from "./stripe" import type { Price } from "./prices" /// One price on a subscription. On current API versions the billing period is on the item. export type SubscriptionItem = { id: string, price?: Price, quantity?: float, metadata?: json, current_period_start?: float, current_period_end?: float, created?: float, } /// A subscription. `customer`, `latest_invoice` and `default_payment_method` are expandable: `idOf` gives their ids. export type Subscription = { id: string, status: string, customer: json, items: { data: SubscriptionItem[], has_more?: boolean }, metadata?: json, currency?: string, cancel_at?: float, cancel_at_period_end?: boolean, canceled_at?: float, collection_method?: string, default_payment_method?: json, discounts?: json, ended_at?: float, latest_invoice?: json, pending_setup_intent?: json, start_date?: float, trial_end?: float, trial_start?: float, created?: float, livemode?: boolean, } /// A price on a new subscription. export type SubscriptionItemParams = { price?: string, quantity?: float, metadata?: Map, extra?: json, } /// A new subscription. `extra` holds any field this type doesn't list. export type SubscriptionParams = { customer: string, items: SubscriptionItemParams[], metadata?: Map, cancel_at_period_end?: boolean, collection_method?: string, days_until_due?: float, default_payment_method?: string, discounts?: { coupon?: string, promotion_code?: string }[], payment_behavior?: string, proration_behavior?: string, trial_end?: float, trial_period_days?: float, extra?: json, } /// A change to one item. Give `id` to change an item, leave it out to add one, and set `deleted` to remove it. export type SubscriptionItemUpdate = { id?: string, price?: string, quantity?: float, deleted?: boolean, metadata?: Map, extra?: json, } /// The fields of a subscription that can change. export type SubscriptionUpdateParams = { items?: SubscriptionItemUpdate[], metadata?: Map, cancel_at_period_end?: boolean, default_payment_method?: string, discounts?: { coupon?: string, promotion_code?: string, discount?: string }[], payment_behavior?: string, proration_behavior?: string, trial_end?: float, extra?: json, } /// What to list. `status` also takes `all`, which includes canceled subscriptions. export type SubscriptionListParams = { customer?: string, price?: string, status?: string, limit?: float, starting_after?: string, ending_before?: string, extra?: json, } /// Creates a subscription. export async fn create( c: Client, params: SubscriptionParams, options: RequestOptions = {}, ): Subscription ! StripeError { return try await request( c, "POST", "/v1/subscriptions", params, options, j => try j as Subscription, ) } /// Gets a subscription by id. export async fn retrieve( c: Client, id: string, options: RequestOptions = {}, ): Subscription ! StripeError { return try await request( c, "GET", `/v1/subscriptions/${segment(id)}`, null, options, j => try j as Subscription, ) } /// Changes the fields given. export async fn update( c: Client, id: string, params: SubscriptionUpdateParams, options: RequestOptions = {}, ): Subscription ! StripeError { return try await request( c, "POST", `/v1/subscriptions/${segment(id)}`, params, options, j => try j as Subscription, ) } /// Cancels a subscription now. To cancel when the period ends, `update` with `cancel_at_period_end: true`. export async fn cancel( c: Client, id: string, options: RequestOptions = {}, ): Subscription ! StripeError { return try await request( c, "DELETE", `/v1/subscriptions/${segment(id)}`, null, options, j => try j as Subscription, ) } /// One page of subscriptions, newest first. Canceled ones are left out unless `status` asks for them. export async fn list( c: Client, params: SubscriptionListParams = {}, options: RequestOptions = {}, ): Page ! StripeError { return try await request( c, "GET", "/v1/subscriptions", params, options, j => try j as Page, ) } /// Every subscription matching `params`, up to `max`. export async fn listAll( c: Client, params: SubscriptionListParams = {}, options: RequestOptions = {}, max: int = 10000, ): Subscription[] ! StripeError { return try await collect( c, "/v1/subscriptions", params, options, j => try j as Page, x => x.id, max, ) } /// Subscriptions matching a search query (`status:"active" AND metadata["site"]:"a1"`). `page` is the `next_page` of the /// page before. export async fn search( c: Client, query: string, page: string? = null, options: RequestOptions = {}, ): SearchPage ! StripeError { return try await request( c, "GET", "/v1/subscriptions/search", { query, page }, options, j => try j as SearchPage, ) }