diff --git a/types/stripe/index.d.ts b/types/stripe/index.d.ts index 12f2b4abea..83fabae861 100644 --- a/types/stripe/index.d.ts +++ b/types/stripe/index.d.ts @@ -2820,27 +2820,23 @@ declare namespace Stripe { metadata: IMetadata; /** - * Display name of the plan + * A brief description of the plan, hidden from customers. */ - name: string; + nickname?: string; /** - * Extra information about a charge for the customer's credit card statement. + * The product whose pricing this plan determines. [Expandable] */ - statement_descriptor: string; - - /** - * Number of trial period days granted when subscribing a customer to this plan. Null if the plan has no trial period. - */ - trial_period_days: number; + product?: string | products.IProduct; } interface IPlanCreationOptions extends IDataOptionsWithMetadata { /** - * Unique string of your choice that will be used to identify this plan when subscribing a customer. This could be an identifier - * like "gold" or a primary key from your own database. + * An identifier randomly generated by Stripe. Used to identify this plan when subscribing a customer. You can optionally override this + * ID, but the ID must be unique across all plans in your Stripe account. You can, however, use the same plan ID in both live and test + * modes. */ - id: string; + id?: string; /** * A positive integer in cents/pence (or 0 for a free plan) representing how much to charge (on a recurring basis). @@ -2858,9 +2854,10 @@ declare namespace Stripe { interval: IntervalUnit; /** - * Name of the plan, to be displayed on invoices and in the web interface. + * The product whose pricing the created plan will represent. This can either be the ID of an existing product, or a dictionary containing + * fields used to create a service product. */ - name: string; + product: string | IPlanCreationOptionsProductHash; /** * The number of intervals between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months. @@ -2869,31 +2866,45 @@ declare namespace Stripe { interval_count?: number; /** - * An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website - * is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. - * The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII - * characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all. + * A brief description of the plan, hidden from customers. */ - statement_descriptor?: string; - - /** - * Specifies a trial period in (an integer number of) days. If you include a trial period, the customer won't be billed for the first time - * until the trial period ends. If the customer cancels before the trial period is over, she'll never be billed at all. - */ - trial_period_days?: number; + nickname?: string; } interface IPlanUpdateOptions extends IDataOptionsWithMetadata { /** - * Name of the plan, to be displayed on invoices and in the web interface. + * A brief description of the plan, hidden from customers. This can be unset by updating the value to null and then saving. */ - name?: string; + nickname?: string; /** - * An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website - * is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. - * The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII - * characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all. + * The product the plan belongs to. Note that after updating, statement descriptors and line items of the plan in active subscriptions will + * be affected. + */ + product?: string; + } + + interface IPlanCreationOptionsProductHash { + /** + * The identifier for the product. Must be unique. If not provided, an identifier will be randomly generated. + */ + id?: string; + + /** + * The product’s name, meant to be displayable to the customer. + */ + name: string; + + /** + * Set of key/value pairs that you can attach to an object. It can be useful for storing additional information about the object in a structured + * format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. + */ + metadata?: IOptionsMetadata; + + /** + * An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. The statement description may not + * include <>”’ characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While + * most banks display this information consistently, some may display it incorrectly or not at all. */ statement_descriptor?: string; } @@ -2923,6 +2934,9 @@ declare namespace Stripe { */ caption: string; + /** + * Time at which the object was created. Measured in seconds since the Unix epoch. + */ created: number; /** @@ -2962,6 +2976,18 @@ declare namespace Stripe { updated: number; + /** + * Extra information about a product which will appear on your customer’s credit card statement. In the case that multiple products are billed + * at once, the first statement descriptor will be used. Only available on products of type=service. + */ + statement_descriptor: string; + + /** + * The type of the product. The product is either of type good, which is eligible for use with Orders and SKUs, or service, which is eligible for + * use with Subscriptions and Plans. + */ + type: ProductType; + /** * A URL of a publicly-accessible webpage for this product. */ @@ -2971,55 +2997,77 @@ declare namespace Stripe { interface IProductCreationOptions extends IDataOptionsWithMetadata { /** * The identifier for the product. Must be unique. If not provided, an identifier will be randomly generated. + * Applicable to both service and good types. */ id?: string; /** * The product’s name, meant to be displayable to the customer. + * Applicable to both service and good types. */ name: string; /** - * Whether or not the product is currently available for purchase. Defaults to true. + * The type of the product. The product is either of type service, which is eligible for use with Subscriptions + * and Plans or good, which is eligible for use with Orders and SKUs. + */ + type: ProductType; + + /** + * Whether or not the product is currently available for purchase. Defaults to true. May only be set if type=good. */ active?: boolean; /** * A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. ["color", "size"]). + * Applicable to both service and good types. */ attribute?: Array; /** - * A short one-line description of the product, meant to be displayable to the customer. + * A short one-line description of the product, meant to be displayable to the customer. May only be set if type=good. */ caption?: string; /** * An array of Connect application names or identifiers that should not be able to order the SKUs for this product. + * May only be set if type=good. */ deactivate_on?: Array; /** - * The product’s description, meant to be displayable to the customer. + * The product’s description, meant to be displayable to the customer. May only be set if type=good. */ description?: string; /** - * A list of up to 8 URLs of images for this product, meant to be displayable to the customer. + * A list of up to 8 URLs of images for this product, meant to be displayable to the customer. May only be set if type=good. */ images?: Array; + /** + * The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own + * package_dimensions. May only be set if type=good. + */ package_dimensions?: IPackageDimensions; /** - * Whether this product is shipped (i.e. physical goods). Defaults to true. + * Whether this product is shipped (i.e. physical goods). Defaults to true. May only be set if type=good. */ shippable?: boolean; /** - * A URL of a publicly-accessible webpage for this product. + * A URL of a publicly-accessible webpage for this product. May only be set if type=good. */ url?: string; + + /** + * An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. The statement description + * may not include <>”’ characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically + * stripped. While most banks display this information consistently, some may display it incorrectly or not at all. + * May only be set if type=service. + */ + statement_descriptor?: string; } interface IProductUpdateOptions extends IDataOptionsWithMetadata { @@ -3056,6 +3104,10 @@ declare namespace Stripe { */ name?: string; + /** + * The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own + * package_dimensions. + */ package_dimensions?: IPackageDimensions; /** @@ -3067,6 +3119,14 @@ declare namespace Stripe { * A URL of a publicly-accessible webpage for this product. */ url?: string; + + /** + * An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. The statement description + * may not include <>”’ characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically + * stripped. While most banks display this information consistently, some may display it incorrectly or not at all. + * May only be set if type=service. + */ + statement_descriptor?: string; } interface IProductListOptions extends IListOptions { @@ -3113,6 +3173,8 @@ declare namespace Stripe { */ width: number; } + + type ProductType = "service" | "good"; } namespace recipientCards { } @@ -4373,6 +4435,11 @@ declare namespace Stripe { */ trial_end?: number | "now"; + /** + * Integer representing the number of trial period days before the customer is charged for the first time. + */ + trial_period_days?: number; + /** * List of subscription items, each with an attached plan. */ @@ -4384,6 +4451,18 @@ declare namespace Stripe { * instructions. Defaults to "charge_automatically". */ billing?: SubscriptionBilling; + + /** + * Number of days a customer has to pay invoices generated by this subscription. + * Only valid for subscriptions where billing=send_invoice. + */ + days_until_due?: number; + + /** + * A future timestamp to anchor the subscription’s billing cycle. This is used to determine the date of the first full invoice, and, for plans + * with month or year intervals, the day of the month for subsequent invoices. + */ + billing_cycle_anchor?: number; } interface ISubscriptionCreationOptions extends ISubscriptionCustCreationOptions { @@ -4456,10 +4535,20 @@ declare namespace Stripe { */ billing?: SubscriptionBilling; + /** + * Number of days a customer has to pay invoices generated by this subscription. Only valid for subscriptions where billing=send_invoice. + */ + days_until_due?: number; + /** * List of subscription items, each with an attached plan. */ items?: ISubscriptionUpdateItem[]; + + /** + * String, unchanged (default) or now. This allows you to reset the billing cycle of a subscription. + */ + billing_cycle_anchor?: "unchanged" | "now"; } interface ISubscriptionCancellationOptions extends IDataOptions { @@ -6986,6 +7075,18 @@ declare namespace Stripe { stripe_account?: string; api_key?: string; + + /** + * Many objects contain the ID of a related object in their response properties. For example, a Charge may have an associated Customer ID. + * Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. + * This parameter is available on all API requests, and applies to the response of that request only. + * + * You can nest expand requests with the dot property. For example, requesting invoice.customer on a charge will expand the invoice property + * into a full Invoice object, and will then expand the customer property on that invoice into a full Customer object. + * + * You can expand multiple objects at once by identifying multiple items in the expand array. + */ + expand?: string[]; } /** diff --git a/types/stripe/stripe-tests.ts b/types/stripe/stripe-tests.ts index b887ae6228..52e8579f45 100644 --- a/types/stripe/stripe-tests.ts +++ b/types/stripe/stripe-tests.ts @@ -251,14 +251,15 @@ stripe.customers.create({ customer.cards.list().then(function (cards) {}); customer.cards.del("card_17xMvXBoqMA9o2xkq6W5gamx").then(function (confirmation) {}); - customer.subscriptions.create({ items: [{ plan: "gold" }] }).then(function (subscription) { }); - customer.subscriptions.create({ items: [{ plan: "gold" }], trial_end: "now" }).then(function (subscription) { }); - customer.subscriptions.create({ items: [{ plan: "gold" }], trial_end: 1516881177 }).then(function (subscription) { }); + customer.subscriptions.create({ items: [{ plan: "gold" }], trial_period_days: 7 }).then(function (subscription) { }); + customer.subscriptions.create({ items: [{ plan: "gold" }], trial_end: "now", billing_cycle_anchor: 1516881177 }).then(function (subscription) { }); + customer.subscriptions.create({ items: [{ plan: "gold" }], trial_end: 1516881177, billing: "send_invoice", days_until_due: 7 }).then(function (subscription) { }); + customer.subscriptions.create({ items: [{ plan: "gold" }], billing: "charge_automatically" }).then(function (subscription) { }); customer.subscriptions.retrieve("sub_8Eluur5KoIKxuy").then(function (subscription) { customer.subscriptions.update("sub_8Eluur5KoIKxuy", { items: [{ id: subscription.items.data[0].id, plan: "silver" }] }).then(function (subscription) { }); }); - customer.subscriptions.update("sub_8Eluur5KoIKxuy", { trial_end: "now" }); - customer.subscriptions.update("sub_8Eluur5KoIKxuy", { trial_end: 1516881177 }); + customer.subscriptions.update("sub_8Eluur5KoIKxuy", { trial_end: "now", billing_cycle_anchor: "now" }); + customer.subscriptions.update("sub_8Eluur5KoIKxuy", { trial_end: 1516881177, billing: "send_invoice", days_until_due: 7, billing_cycle_anchor: "unchanged" }); customer.subscriptions.list().then(function (subscriptions) { }); customer.subscriptions.del("sub_8Eluur5KoIKxuy").then(function (subscription) { }); customer.subscriptions.deleteDiscount("sub_8Eluur5KoIKxuy").then(function (confirmation) { }); @@ -756,7 +757,19 @@ stripe.accounts.createExternalAccount("", { external_account: "tok_15V2YhEe31JkL //#region Products tests // ################################################################################## - +stripe.products.create({ + name: "My amazing product", + type: "service" +}, function (err, coupon) { + // asynchronously called +}); +stripe.products.create({ + name: "My amazing product", + type: "service" +}).then(function (product) { + // asynchronously called + const prodType: "service" | "good" = product.type; +}); //#endregion @@ -1068,51 +1081,77 @@ stripe.payouts.cancel( //#region Plans tests // ################################################################################## +// all product hash options stripe.plans.create({ amount: 2000, interval: "month", - name: "Amazing Gold Plan", + product: { + name: "Amazing Gold Plan", + statement_descriptor: "Gold Plan", + metadata: { + plan_id: "goldplan123" + } + }, + nickname: "Something to remember me by", currency: "usd", - id: "gold" + id: "gold-plan" }, function (err, plan) { // asynchronously called - }); +}); + +// minimum options with product hash stripe.plans.create({ amount: 2000, - interval: "month", - name: "Amazing Gold Plan", currency: "usd", - id: "gold" + interval: "month", + product: { + name: "Amazing Gold Plan" + } }).then(function (plan) { // asynchronously called }); +// minimum options with product id +stripe.plans.create({ + amount: 2000, + currency: "usd", + interval: "month", + product: "prod_UT1t06yZ3iBEHi" +}).then(function (plan) { + // asynchronously called + const productId = plan.product as string; +}); + stripe.plans.retrieve( - "platypi-dev", + "gold-plan", + { + expand: ["product"] + }, function (err, plan) { // asynchronously called + const product = plan.product as Stripe.products.IProduct; } ); -stripe.plans.retrieve("platypi-dev").then(function (plan) { +stripe.plans.retrieve("gold-plan").then(function (plan) { // asynchronously called }); -stripe.plans.update("platypi-dev", { - name: "New plan name" +stripe.plans.update("gold-plan", { + product: "prod_UT1t06yZ3iBEHi" }, function (err, plan) { // asynchronously called }); -stripe.plans.update("platypi-dev", { name: "New plan name" }).then(function (plan) { +stripe.plans.update("gold-plan", { nickname: "New gold plan nickname" }).then(function (plan) { // asynchronously called }); stripe.plans.del( - "platypi-dev", + "gold-plan", function (err, confirmation) { // asynchronously called } ); -stripe.plans.del("platypi-dev").then(function (confirmation) { +stripe.plans.del("gold-plan").then(function (confirmation) { // asynchronously called });