@return Crest::Request

@return Crest::Request

@return Crest::Request

@return Crest::Request

@return Crest::Request

@return Crest::Request

@return Crest::Request

@return Crest::Request

Cancels a customer’s subscription immediately. The customer will not be charged again for the subscription.

Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually deleted. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.

By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.

@required @param subscription_exposed_id [String?] @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_now [Bool?] Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items. Defaults to `true`. @optional @param prorate [Bool?] Will generate a proration invoice item that credits remaining unused time until the subscription period end. Defaults to `false`. @return [Stripe::Subscription]

<p>Cancels a customer’s subscription immediately. The customer will not be charged again for the subscription.</p> <p>Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually <a href=&quot;#delete_invoiceitem&quot;>deleted</a>. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.</p> <p>By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.</p> @required @param subscription_exposed_id [String?] @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_now [Bool?] Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items. Defaults to true. @optional @param prorate [Bool?] Will generate a proration invoice item that credits remaining unused time until the subscription period end. Defaults to false. @return nil

Removes the currently applied discount on a subscription.

@required @param subscription_exposed_id [String?] @return [Stripe::DeletedDiscount]

<p>Removes the currently applied discount on a subscription.</p> @required @param subscription_exposed_id [String?] @return nil

<p>Removes the currently applied discount on a subscription.</p> @required @param subscription_exposed_id [String?] @return [Tuple(Stripe::DeletedDiscount, Integer, Hash)] Stripe::DeletedDiscount, response status code and response headers

<p>Cancels a customer’s subscription immediately. The customer will not be charged again for the subscription.</p> <p>Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period, unless manually <a href=&quot;#delete_invoiceitem&quot;>deleted</a>. If you’ve set the subscription to cancel at the end of the period, any pending prorations will also be left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations will be removed.</p> <p>By default, upon subscription cancellation, Stripe will stop automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.</p> @required @param subscription_exposed_id [String?] @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_now [Bool?] Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items. Defaults to true. @optional @param prorate [Bool?] Will generate a proration invoice item that credits remaining unused time until the subscription period end. Defaults to false. @return [Tuple(Stripe::Subscription, Integer, Hash)] Stripe::Subscription, response status code and response headers

By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.

@optional @param ending_before [String?] A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. @optional @param starting_after [String?] A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param test_clock [String?] Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set. @optional @param price [String?] Filter for subscriptions that contain this recurring price ID. @optional @param automatic_tax [Stripe::AutomaticTaxFilterParams?] Filter subscriptions by their automatic tax settings. @optional @param created [Stripe::GetAccountsCreatedParameter?] Only return subscriptions that were created during the given date interval. @optional @param current_period_end [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_end falls within the given date interval. @optional @param current_period_start [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_start falls within the given date interval. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @optional @param customer [String?] The ID of the customer whose subscriptions will be retrieved. @optional @param plan [String?] The ID of the plan whose subscriptions will be retrieved. @optional @param collection_method [String?] The collection method of the subscriptions to retrieve. Either `charge_automatically` or `send_invoice`. @optional @param status [String?] The status of the subscriptions to retrieve. Passing in a value of `canceled` will return all canceled subscriptions, including those belonging to deleted customers. Pass `ended` to find subscriptions that are canceled and subscriptions that are expired due to [incomplete payment](https://stripe.com/docs/billing/subscriptions/overview#subscription-statuses). Passing in a value of `all` will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned. @return [Stripe::SubscriptionsSubscriptionList]

<p>By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify <code>status=canceled</code>.</p> @optional @param ending_before [String?] A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. @optional @param starting_after [String?] A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param test_clock [String?] Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set. @optional @param price [String?] Filter for subscriptions that contain this recurring price ID. @optional @param automatic_tax [Stripe::AutomaticTaxFilterParams?] Filter subscriptions by their automatic tax settings. @optional @param created [Stripe::GetAccountsCreatedParameter?] Only return subscriptions that were created during the given date interval. @optional @param current_period_end [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_end falls within the given date interval. @optional @param current_period_start [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_start falls within the given date interval. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @optional @param customer [String?] The ID of the customer whose subscriptions will be retrieved. @optional @param plan [String?] The ID of the plan whose subscriptions will be retrieved. @optional @param collection_method [String?] The collection method of the subscriptions to retrieve. Either charge_automatically or send_invoice. @optional @param status [String?] The status of the subscriptions to retrieve. Passing in a value of canceled will return all canceled subscriptions, including those belonging to deleted customers. Pass ended to find subscriptions that are canceled and subscriptions that are expired due to incomplete payment. Passing in a value of all will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned. @return nil

Search for subscriptions you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

@required @param query [String?] The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for subscriptions](https://stripe.com/docs/search#query-fields-for-subscriptions). @optional @param page [String?] A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return [Stripe::SearchResult]

<p>Search for subscriptions you’ve previously created using Stripe’s <a href=&quot;/docs/search#search-query-language&quot;>Search Query Language</a>. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.</p> @required @param query [String?] The search query string. See search query language and the list of supported query fields for subscriptions. @optional @param page [String?] A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return nil

<p>Search for subscriptions you’ve previously created using Stripe’s <a href=&quot;/docs/search#search-query-language&quot;>Search Query Language</a>. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.</p> @required @param query [String?] The search query string. See search query language and the list of supported query fields for subscriptions. @optional @param page [String?] A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return [Tuple(Stripe::SearchResult, Integer, Hash)] Stripe::SearchResult, response status code and response headers

Retrieves the subscription with the given ID.

@required @param subscription_exposed_id [String?] @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return [Stripe::Subscription]

<p>Retrieves the subscription with the given ID.</p> @required @param subscription_exposed_id [String?] @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return nil

<p>Retrieves the subscription with the given ID.</p> @required @param subscription_exposed_id [String?] @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @return [Tuple(Stripe::Subscription, Integer, Hash)] Stripe::Subscription, response status code and response headers

<p>By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify <code>status=canceled</code>.</p> @optional @param ending_before [String?] A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. @optional @param starting_after [String?] A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. @optional @param limit [Int32?] A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. @optional @param test_clock [String?] Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set. @optional @param price [String?] Filter for subscriptions that contain this recurring price ID. @optional @param automatic_tax [Stripe::AutomaticTaxFilterParams?] Filter subscriptions by their automatic tax settings. @optional @param created [Stripe::GetAccountsCreatedParameter?] Only return subscriptions that were created during the given date interval. @optional @param current_period_end [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_end falls within the given date interval. @optional @param current_period_start [Stripe::GetAccountsCreatedParameter?] Only return subscriptions whose current_period_start falls within the given date interval. @optional @param expand [Array(Array(String))?] Specifies which fields in the response should be expanded. @optional @param customer [String?] The ID of the customer whose subscriptions will be retrieved. @optional @param plan [String?] The ID of the plan whose subscriptions will be retrieved. @optional @param collection_method [String?] The collection method of the subscriptions to retrieve. Either charge_automatically or send_invoice. @optional @param status [String?] The status of the subscriptions to retrieve. Passing in a value of canceled will return all canceled subscriptions, including those belonging to deleted customers. Pass ended to find subscriptions that are canceled and subscriptions that are expired due to incomplete payment. Passing in a value of all will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned. @return [Tuple(Stripe::SubscriptionsSubscriptionList, Integer, Hash)] Stripe::SubscriptionsSubscriptionList, response status code and response headers

Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.

When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment.

To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

@required @param customer [String?] The identifier of the customer to subscribe. @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param backdate_start_date [Int32?] For new subscriptions, a past timestamp to backdate the subscription's start date to. If set, the first invoice will contain a proration for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor. @optional @param billing_cycle_anchor [Int32?] A future timestamp in UTC format to anchor the subscription's [billing cycle](https://stripe.com/docs/subscriptions/billing-cycle). The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for `week` intervals, the day of month for `month` and `year` intervals, and the month of year for `year` intervals. @optional @param billing_cycle_anchor_config [Stripe::BillingCycleAnchorConfigParam?] @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Int32?] A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using `proration_behavior`. If set during a future period, this will always cause a proration for that period. @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (`current_period_end`). Defaults to `false`. @optional @param collection_method [String?] Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. @optional @param currency [String?] Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source). @optional @param default_source [String?] ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If `default_payment_method` is also set, `default_payment_method` will take precedence. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source). @optional @param default_tax_rates [Stripe::PostSubscriptionsRequestDefaultTaxRates?] @optional @param description [String?] The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemCreateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param payment_behavior [String?] Only applies to subscriptions with `collection_method=charge_automatically`. Use `allow_incomplete` to create Subscriptions with `status=incomplete` if the first invoice can't be paid. Creating Subscriptions with this status allows you to manage scenarios where additional customer actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior. Use `default_incomplete` to create Subscriptions with `status=incomplete` when the first invoice requires payment, otherwise start as active. Subscriptions transition to `status=active` when successfully confirming the PaymentIntent on the first invoice. This allows simpler management of scenarios where additional customer actions are needed to pay a subscription’s invoice, such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. If the PaymentIntent is not confirmed within 23 hours Subscriptions transition to `status=incomplete_expired`, which is a terminal state. Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's first invoice can't be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further customer action is needed, this parameter doesn't create a Subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more. `pending_if_incomplete` is only used with updates and cannot be passed when creating a Subscription. Subscriptions with `collection_method=send_invoice` are automatically activated regardless of the first Invoice status. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. @optional @param proration_behavior [String?] Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) resulting from the `billing_cycle_anchor`. If no value is passed, the default is `create_prorations`. @optional @param transfer_data [Stripe::TransferDataSpecs?] @optional @param trial_end [Stripe::PostSubscriptionsRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. @optional @param trial_period_days [Int32?] Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return [Stripe::Subscription]

<p>Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.</p> <p>When you create a subscription with <code>collection_method=charge_automatically</code>, the first invoice is finalized as part of the request. The <code>payment_behavior</code> parameter determines the exact behavior of the initial payment.</p> <p>To start subscriptions where the first invoice always begins in a <code>draft</code> status, use <a href=&quot;/docs/billing/subscriptions/subscription-schedules#managing&quot;>subscription schedules</a> instead. Schedules provide the flexibility to model more complex billing configurations that change over time.</p> @required @param customer [String?] The identifier of the customer to subscribe. @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param backdate_start_date [Int32?] For new subscriptions, a past timestamp to backdate the subscription's start date to. If set, the first invoice will contain a proration for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor. @optional @param billing_cycle_anchor [Int32?] A future timestamp in UTC format to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. @optional @param billing_cycle_anchor_config [Stripe::BillingCycleAnchorConfigParam?] @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Int32?] A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period. @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false. @optional @param collection_method [String?] Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param currency [String?] Three-letter ISO currency code, in lowercase. Must be a supported currency. @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_source [String?] ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_tax_rates [Stripe::PostSubscriptionsRequestDefaultTaxRates?] @optional @param description [String?] The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemCreateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param payment_behavior [String?] Only applies to subscriptions with collection_method=charge_automatically. Use allow_incomplete to create Subscriptions with status=incomplete if the first invoice can't be paid. Creating Subscriptions with this status allows you to manage scenarios where additional customer actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more. This is the default behavior. Use default_incomplete to create Subscriptions with status=incomplete when the first invoice requires payment, otherwise start as active. Subscriptions transition to status=active when successfully confirming the PaymentIntent on the first invoice. This allows simpler management of scenarios where additional customer actions are needed to pay a subscription’s invoice, such as failed payments, SCA regulation, or collecting a mandate for a bank debit payment method. If the PaymentIntent is not confirmed within 23 hours Subscriptions transition to status=incomplete_expired, which is a terminal state. Use error_if_incomplete if you want Stripe to return an HTTP 402 status code if a subscription's first invoice can't be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further customer action is needed, this parameter doesn't create a Subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the changelog to learn more. pending_if_incomplete is only used with updates and cannot be passed when creating a Subscription. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param proration_behavior [String?] Determines how to handle prorations resulting from the billing_cycle_anchor. If no value is passed, the default is create_prorations. @optional @param transfer_data [Stripe::TransferDataSpecs?] @optional @param trial_end [Stripe::PostSubscriptionsRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more. @optional @param trial_period_days [Int32?] Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See Using trial periods on subscriptions to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return nil

Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the create preview endpoint.

By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a 100 price, they’ll be billed 100 immediately. If on May 15 they switch to a 200 price, then on June 1 they’ll be billed 250 (200 for a renewal of her subscription, plus a 50 prorating adjustment for half of the previous month’s 100 difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes.

Switching prices does not normally change the billing date or generate an immediate charge unless:

• The billing interval is changed (for example, from monthly to yearly).
• The subscription moves from free to paid.
• A trial starts or ends.

In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how Stripe immediately attempts payment for subscription changes.

If you want to charge for an upgrade immediately, pass proration_behavior as always_invoice to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass create_prorations, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually invoice the customer.

If you don’t want to prorate, set the proration_behavior option to none. With this option, the customer is billed 100 on May 1 and 200 on June 1. Similarly, if you set proration_behavior to none when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription.

Updating the quantity on a subscription many times in an hour may result in rate limiting. If you need to bill for a frequently changing quantity, consider integrating usage-based billing instead.

@required @param subscription_exposed_id [String?] @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param billing_cycle_anchor [String?] Either `now` or `unchanged`. Setting the value to `now` resets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Stripe::PostSubscriptionsSubscriptionExposedIdRequestCancelAt?] @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (`current_period_end`). Defaults to `false`. @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param collection_method [String?] Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where `collection_method` is set to `send_invoice`. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over `default_source`. If neither are set, invoices will use the customer's [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](https://stripe.com/docs/api/customers/object#customer_object-default_source). @optional @param default_source [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultSource?] @optional @param default_tax_rates [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultTaxRates?] @optional @param description [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDescription?] @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemUpdateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param pause_collection [Stripe::PostSubscriptionsSubscriptionExposedIdRequestPauseCollection?] @optional @param payment_behavior [String?] Use `allow_incomplete` to transition the subscription to `status=past_due` if a payment is required but cannot be paid. This allows you to manage scenarios where additional user actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more. This is the default behavior. Use `default_incomplete` to transition the subscription to `status=past_due` when payment is required and await explicit confirmation of the invoice's payment intent. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates). When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes). Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use `discounts` instead. @optional @param proration_behavior [String?] Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with [upcoming invoice](https://stripe.com/docs/api#upcoming_invoice) endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations. @optional @param transfer_data [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTransferData?] @optional @param trial_end [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `trial_end` is not allowed. See [Using trial periods on subscriptions](https://stripe.com/docs/billing/subscriptions/trials) to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return [Stripe::Subscription]

<p>Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the <a href=&quot;/docs/api/invoices/create_preview&quot;>create preview</a> endpoint.</p> <p>By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a <currency>100</currency> price, they’ll be billed <currency>100</currency> immediately. If on May 15 they switch to a <currency>200</currency> price, then on June 1 they’ll be billed <currency>250</currency> (<currency>200</currency> for a renewal of her subscription, plus a <currency>50</currency> prorating adjustment for half of the previous month’s <currency>100</currency> difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes.</p> <p>Switching prices does not normally change the billing date or generate an immediate charge unless:</p> <ul> <li>The billing interval is changed (for example, from monthly to yearly).</li> <li>The subscription moves from free to paid.</li> <li>A trial starts or ends.</li> </ul> <p>In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how <a href=&quot;/billing/subscriptions/upgrade-downgrade#immediate-payment&quot;>Stripe immediately attempts payment for subscription changes</a>.</p> <p>If you want to charge for an upgrade immediately, pass <code>proration_behavior</code> as <code>always_invoice</code> to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass <code>create_prorations</code>, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually <a href=&quot;/docs/api/invoices/create&quot;>invoice the customer</a>.</p> <p>If you don’t want to prorate, set the <code>proration_behavior</code> option to <code>none</code>. With this option, the customer is billed <currency>100</currency> on May 1 and <currency>200</currency> on June 1. Similarly, if you set <code>proration_behavior</code> to <code>none</code> when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription.</p> <p>Updating the quantity on a subscription many times in an hour may result in <a href=&quot;/docs/rate-limits&quot;>rate limiting</a>. If you need to bill for a frequently changing quantity, consider integrating <a href=&quot;/docs/billing/subscriptions/usage-based&quot;>usage-based billing</a> instead.</p> @required @param subscription_exposed_id [String?] @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param billing_cycle_anchor [String?] Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle documentation. @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Stripe::PostSubscriptionsSubscriptionExposedIdRequestCancelAt?] @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false. @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param collection_method [String?] Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_source [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultSource?] @optional @param default_tax_rates [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultTaxRates?] @optional @param description [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDescription?] @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemUpdateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param pause_collection [Stripe::PostSubscriptionsSubscriptionExposedIdRequestPauseCollection?] @optional @param payment_behavior [String?] Use allow_incomplete to transition the subscription to status=past_due if a payment is required but cannot be paid. This allows you to manage scenarios where additional user actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more. This is the default behavior. Use default_incomplete to transition the subscription to status=past_due when payment is required and await explicit confirmation of the invoice's payment intent. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, SCA regulation, or collecting a mandate for a bank debit payment method. Use pending_if_incomplete to update the subscription using pending updates. When you use pending_if_incomplete you can only pass the parameters supported by pending updates. Use error_if_incomplete if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the changelog to learn more. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param proration_behavior [String?] Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations. @optional @param transfer_data [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTransferData?] @optional @param trial_end [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return nil

<p>Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the <a href=&quot;/docs/api/invoices/create_preview&quot;>create preview</a> endpoint.</p> <p>By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a <currency>100</currency> price, they’ll be billed <currency>100</currency> immediately. If on May 15 they switch to a <currency>200</currency> price, then on June 1 they’ll be billed <currency>250</currency> (<currency>200</currency> for a renewal of her subscription, plus a <currency>50</currency> prorating adjustment for half of the previous month’s <currency>100</currency> difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes.</p> <p>Switching prices does not normally change the billing date or generate an immediate charge unless:</p> <ul> <li>The billing interval is changed (for example, from monthly to yearly).</li> <li>The subscription moves from free to paid.</li> <li>A trial starts or ends.</li> </ul> <p>In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how <a href=&quot;/billing/subscriptions/upgrade-downgrade#immediate-payment&quot;>Stripe immediately attempts payment for subscription changes</a>.</p> <p>If you want to charge for an upgrade immediately, pass <code>proration_behavior</code> as <code>always_invoice</code> to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass <code>create_prorations</code>, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually <a href=&quot;/docs/api/invoices/create&quot;>invoice the customer</a>.</p> <p>If you don’t want to prorate, set the <code>proration_behavior</code> option to <code>none</code>. With this option, the customer is billed <currency>100</currency> on May 1 and <currency>200</currency> on June 1. Similarly, if you set <code>proration_behavior</code> to <code>none</code> when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription.</p> <p>Updating the quantity on a subscription many times in an hour may result in <a href=&quot;/docs/rate-limits&quot;>rate limiting</a>. If you need to bill for a frequently changing quantity, consider integrating <a href=&quot;/docs/billing/subscriptions/usage-based&quot;>usage-based billing</a> instead.</p> @required @param subscription_exposed_id [String?] @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param billing_cycle_anchor [String?] Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle documentation. @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Stripe::PostSubscriptionsSubscriptionExposedIdRequestCancelAt?] @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false. @optional @param cancellation_details [Stripe::CancellationDetailsParam?] @optional @param collection_method [String?] Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_source [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultSource?] @optional @param default_tax_rates [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDefaultTaxRates?] @optional @param description [Stripe::PostSubscriptionsSubscriptionExposedIdRequestDescription?] @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemUpdateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param pause_collection [Stripe::PostSubscriptionsSubscriptionExposedIdRequestPauseCollection?] @optional @param payment_behavior [String?] Use allow_incomplete to transition the subscription to status=past_due if a payment is required but cannot be paid. This allows you to manage scenarios where additional user actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more. This is the default behavior. Use default_incomplete to transition the subscription to status=past_due when payment is required and await explicit confirmation of the invoice's payment intent. This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice. Such as failed payments, SCA regulation, or collecting a mandate for a bank debit payment method. Use pending_if_incomplete to update the subscription using pending updates. When you use pending_if_incomplete you can only pass the parameters supported by pending updates. Use error_if_incomplete if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the changelog to learn more. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param proration_behavior [String?] Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations. @optional @param transfer_data [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTransferData?] @optional @param trial_end [Stripe::PostSubscriptionsSubscriptionExposedIdRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return [Tuple(Stripe::Subscription, Integer, Hash)] Stripe::Subscription, response status code and response headers

Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become active, and if payment fails the subscription will be past_due. The resumption invoice will void automatically if not paid by the expiration date.

@required @param subscription [String?] @optional @param billing_cycle_anchor [String?] Either `now` or `unchanged`. Setting the value to `now` resets the subscription's billing cycle anchor to the current time (in UTC). Setting the value to `unchanged` advances the subscription's billing cycle anchor to the period that surrounds the current time. For more information, see the billing cycle [documentation](https://stripe.com/docs/billing/subscriptions/billing-cycle). @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param proration_behavior [String?] Determines how to handle [prorations](https://stripe.com/docs/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same proration that was previewed with [upcoming invoice](https://stripe.com/docs/api#retrieve_customer_invoice) endpoint. @return [Stripe::Subscription]

<p>Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become <code>active</code>, and if payment fails the subscription will be <code>past_due</code>. The resumption invoice will void automatically if not paid by the expiration date.</p> @required @param subscription [String?] @optional @param billing_cycle_anchor [String?] Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time (in UTC). Setting the value to unchanged advances the subscription's billing cycle anchor to the period that surrounds the current time. For more information, see the billing cycle documentation. @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param proration_behavior [String?] Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. @return nil

<p>Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. If a resumption invoice is generated, it must be paid or marked uncollectible before the subscription will be unpaused. If payment succeeds the subscription will become <code>active</code>, and if payment fails the subscription will be <code>past_due</code>. The resumption invoice will void automatically if not paid by the expiration date.</p> @required @param subscription [String?] @optional @param billing_cycle_anchor [String?] Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time (in UTC). Setting the value to unchanged advances the subscription's billing cycle anchor to the period that surrounds the current time. For more information, see the billing cycle documentation. @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param proration_behavior [String?] Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations. @optional @param proration_date [Int32?] If set, the proration will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. @return [Tuple(Stripe::Subscription, Integer, Hash)] Stripe::Subscription, response status code and response headers

<p>Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.</p> <p>When you create a subscription with <code>collection_method=charge_automatically</code>, the first invoice is finalized as part of the request. The <code>payment_behavior</code> parameter determines the exact behavior of the initial payment.</p> <p>To start subscriptions where the first invoice always begins in a <code>draft</code> status, use <a href=&quot;/docs/billing/subscriptions/subscription-schedules#managing&quot;>subscription schedules</a> instead. Schedules provide the flexibility to model more complex billing configurations that change over time.</p> @required @param customer [String?] The identifier of the customer to subscribe. @optional @param add_invoice_items [Array(Stripe::AddInvoiceItemEntry)?] A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items. @optional @param application_fee_percent [Stripe::PostSubscriptionsRequestApplicationFeePercent?] @optional @param automatic_tax [Stripe::AutomaticTaxConfig?] @optional @param backdate_start_date [Int32?] For new subscriptions, a past timestamp to backdate the subscription's start date to. If set, the first invoice will contain a proration for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor. @optional @param billing_cycle_anchor [Int32?] A future timestamp in UTC format to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. @optional @param billing_cycle_anchor_config [Stripe::BillingCycleAnchorConfigParam?] @optional @param billing_thresholds [Stripe::PostSubscriptionsRequestBillingThresholds?] @optional @param cancel_at [Int32?] A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period. @optional @param cancel_at_period_end [Bool?] Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false. @optional @param collection_method [String?] Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically. @optional @param coupon [String?] The ID of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param currency [String?] Three-letter ISO currency code, in lowercase. Must be a supported currency. @optional @param days_until_due [Int32?] Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice. @optional @param default_payment_method [String?] ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_source [String?] ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source. @optional @param default_tax_rates [Stripe::PostSubscriptionsRequestDefaultTaxRates?] @optional @param description [String?] The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. @optional @param discounts [Stripe::PostSubscriptionsRequestDiscounts?] @optional @param expand [Array(String)?] Specifies which fields in the response should be expanded. @optional @param invoice_settings [Stripe::InvoiceSettingsParam?] @optional @param items [Array(Stripe::SubscriptionItemCreateParams)?] A list of up to 20 subscription items, each with an attached price. @optional @param metadata [Stripe::PostAccountsRequestMetadata?] @optional @param off_session [Bool?] Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session). @optional @param on_behalf_of [Stripe::PostSubscriptionsRequestOnBehalfOf?] @optional @param payment_behavior [String?] Only applies to subscriptions with collection_method=charge_automatically. Use allow_incomplete to create Subscriptions with status=incomplete if the first invoice can't be paid. Creating Subscriptions with this status allows you to manage scenarios where additional customer actions are needed to pay a subscription's invoice. For example, SCA regulation may require 3DS authentication to complete payment. See the SCA Migration Guide for Billing to learn more. This is the default behavior. Use default_incomplete to create Subscriptions with status=incomplete when the first invoice requires payment, otherwise start as active. Subscriptions transition to status=active when successfully confirming the PaymentIntent on the first invoice. This allows simpler management of scenarios where additional customer actions are needed to pay a subscription’s invoice, such as failed payments, SCA regulation, or collecting a mandate for a bank debit payment method. If the PaymentIntent is not confirmed within 23 hours Subscriptions transition to status=incomplete_expired, which is a terminal state. Use error_if_incomplete if you want Stripe to return an HTTP 402 status code if a subscription's first invoice can't be paid. For example, if a payment method requires 3DS authentication due to SCA regulation and further customer action is needed, this parameter doesn't create a Subscription and returns an error instead. This was the default behavior for API versions prior to 2019-03-14. See the changelog to learn more. pending_if_incomplete is only used with updates and cannot be passed when creating a Subscription. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status. @optional @param payment_settings [Stripe::PaymentSettings?] @optional @param pending_invoice_item_interval [Stripe::PostSubscriptionsRequestPendingInvoiceItemInterval?] @optional @param promotion_code [String?] The promotion code to apply to this subscription. A promotion code applied to a subscription will only affect invoices created for that particular subscription. This field has been deprecated and will be removed in a future API version. Use discounts instead. @optional @param proration_behavior [String?] Determines how to handle prorations resulting from the billing_cycle_anchor. If no value is passed, the default is create_prorations. @optional @param transfer_data [Stripe::TransferDataSpecs?] @optional @param trial_end [Stripe::PostSubscriptionsRequestTrialEnd?] @optional @param trial_from_plan [Bool?] Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more. @optional @param trial_period_days [Int32?] Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See Using trial periods on subscriptions to learn more. @optional @param trial_settings [Stripe::TrialSettingsConfig?] @return [Tuple(Stripe::Subscription, Integer, Hash)] Stripe::Subscription, response status code and response headers