Class: Stripe::Subscription

Inherits:
APIResource show all
Extended by:
APIOperations::Create, APIOperations::List, APIOperations::Search
Includes:
APIOperations::Save
Defined in:
lib/stripe/resources/subscription.rb

Overview

Subscriptions allow you to charge a customer on a recurring basis.

Related guide: Creating subscriptions

Defined Under Namespace

Classes: AutomaticTax, BillingCycleAnchorConfig, BillingMode, BillingSchedule, BillingThresholds, CancellationDetails, InvoiceSettings, LastPriceMigrationError, ManagedPayments, PauseCollection, PaymentSettings, PendingInvoiceItemInterval, PendingUpdate, Prebilling, PresentmentDetails, StatusDetails, TransferData, TrialSettings

Constant Summary collapse

OBJECT_NAME = 
"subscription"

Constants inherited from StripeObject

Stripe::StripeObject::RESERVED_FIELD_NAMES

Instance Attribute Summary collapse

Attributes inherited from APIResource

#save_with_parent

Attributes inherited from StripeObject

#last_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Create

create

Methods included from APIOperations::List

list

Methods included from APIOperations::Search

_search

Methods included from APIOperations::Save

included, #save

Methods inherited from APIResource

class_name, custom_method, #refresh, #request_stripe_object, resource_url, #resource_url, retrieve, save_nested_resource

Methods included from APIOperations::Request

included

Methods inherited from StripeObject

#==, #[], #[]=, #_get_inner_class_type, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #each, #eql?, field_encodings, #hash, #initialize, #inspect, #keys, #marshal_dump, #marshal_load, protected_fields, #serialize_params, #to_hash, #to_json, #to_s, #update_attributes, #values

Constructor Details

This class inherits a constructor from Stripe::StripeObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Stripe::StripeObject

Instance Attribute Details

#application ⇒ Object (readonly)

ID of the Connect Application that created the subscription.



910
911
912
 
# File 'lib/stripe/resources/subscription.rb', line 910

def application
  @application
end

#application_fee_percent ⇒ Object (readonly)

A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.



912
913
914
 
# File 'lib/stripe/resources/subscription.rb', line 912

def application_fee_percent
  @application_fee_percent
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



914
915
916
 
# File 'lib/stripe/resources/subscription.rb', line 914

def automatic_tax
  @automatic_tax
end

#billing_cadence ⇒ Object (readonly)

The Billing Cadence which controls the timing of recurring invoice generation for this subscription.If unset, the subscription will bill according to its own configured schedule and create its own invoices.If set, this subscription will be billed by the cadence instead, potentially sharing invoices with the other subscriptions linked to that Cadence.



916
917
918
 
# File 'lib/stripe/resources/subscription.rb', line 916

def billing_cadence
  @billing_cadence
end

#billing_cycle_anchor ⇒ Object (readonly)

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. The timestamp is in UTC format.



918
919
920
 
# File 'lib/stripe/resources/subscription.rb', line 918

def billing_cycle_anchor
  @billing_cycle_anchor
end

#billing_cycle_anchor_config ⇒ Object (readonly)

The fixed values used to calculate the billing_cycle_anchor.



920
921
922
 
# File 'lib/stripe/resources/subscription.rb', line 920

def billing_cycle_anchor_config
  @billing_cycle_anchor_config
end

#billing_mode ⇒ Object (readonly)

The billing mode of the subscription.



922
923
924
 
# File 'lib/stripe/resources/subscription.rb', line 922

def billing_mode
  @billing_mode
end

#billing_schedules ⇒ Object (readonly)

Billing schedules for this subscription.



924
925
926
 
# File 'lib/stripe/resources/subscription.rb', line 924

def billing_schedules
  @billing_schedules
end

#billing_thresholds ⇒ Object (readonly)

Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period



926
927
928
 
# File 'lib/stripe/resources/subscription.rb', line 926

def billing_thresholds
  @billing_thresholds
end

#cancel_at ⇒ Object (readonly)

A date in the future at which the subscription will automatically get canceled



928
929
930
 
# File 'lib/stripe/resources/subscription.rb', line 928

def cancel_at
  @cancel_at
end

#cancel_at_period_end ⇒ Object (readonly)

Whether this subscription will (if status=active) or did (if status=canceled) cancel at the end of the current billing period.



930
931
932
 
# File 'lib/stripe/resources/subscription.rb', line 930

def cancel_at_period_end
  @cancel_at_period_end
end

#canceled_at ⇒ Object (readonly)

If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will reflect the time of the most recent update request, not the end of the subscription period when the subscription is automatically moved to a canceled state.



932
933
934
 
# File 'lib/stripe/resources/subscription.rb', line 932

def canceled_at
  @canceled_at
end

#cancellation_details ⇒ Object (readonly)

Details about why this subscription was cancelled



934
935
936
 
# File 'lib/stripe/resources/subscription.rb', line 934

def cancellation_details
  @cancellation_details
end

#collection_method ⇒ Object (readonly)

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.



936
937
938
 
# File 'lib/stripe/resources/subscription.rb', line 936

def collection_method
  @collection_method
end

#created ⇒ Object (readonly)

Time at which the object was created. Measured in seconds since the Unix epoch.



938
939
940
 
# File 'lib/stripe/resources/subscription.rb', line 938

def created
  @created
end

#currency ⇒ Object (readonly)

Three-letter ISO currency code, in lowercase. Must be a supported currency.



940
941
942
 
# File 'lib/stripe/resources/subscription.rb', line 940

def currency
  @currency
end

#customer ⇒ Object (readonly)

ID of the customer who owns the subscription.



942
943
944
 
# File 'lib/stripe/resources/subscription.rb', line 942

def customer
  @customer
end

#customer_account ⇒ Object (readonly)

ID of the account representing the customer who owns the subscription.



944
945
946
 
# File 'lib/stripe/resources/subscription.rb', line 944

def 
  @customer_account
end

#days_until_due ⇒ Object (readonly)

Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where collection_method=charge_automatically.



946
947
948
 
# File 'lib/stripe/resources/subscription.rb', line 946

def days_until_due
  @days_until_due
end

#default_payment_method ⇒ Object (readonly)

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.



948
949
950
 
# File 'lib/stripe/resources/subscription.rb', line 948

def default_payment_method
  @default_payment_method
end

#default_source ⇒ Object (readonly)

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.



950
951
952
 
# File 'lib/stripe/resources/subscription.rb', line 950

def default_source
  @default_source
end

#default_tax_rates ⇒ Object (readonly)

The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription.



952
953
954
 
# File 'lib/stripe/resources/subscription.rb', line 952

def default_tax_rates
  @default_tax_rates
end

#description ⇒ Object (readonly)

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.



954
955
956
 
# File 'lib/stripe/resources/subscription.rb', line 954

def description
  @description
end

#discounts ⇒ Object (readonly)

The discounts applied to the subscription. Subscription item discounts are applied before subscription discounts. Use expand[]=discounts to expand each discount.



956
957
958
 
# File 'lib/stripe/resources/subscription.rb', line 956

def discounts
  @discounts
end

#ended_at ⇒ Object (readonly)

If the subscription has ended, the date the subscription ended.



958
959
960
 
# File 'lib/stripe/resources/subscription.rb', line 958

def ended_at
  @ended_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



960
961
962
 
# File 'lib/stripe/resources/subscription.rb', line 960

def id
  @id
end

#invoice_settings ⇒ Object (readonly)

Attribute for field invoice_settings



962
963
964
 
# File 'lib/stripe/resources/subscription.rb', line 962

def invoice_settings
  @invoice_settings
end

#items ⇒ Object (readonly)

List of subscription items, each with an attached price.



964
965
966
 
# File 'lib/stripe/resources/subscription.rb', line 964

def items
  @items
end

#last_price_migration_error ⇒ Object (readonly)

Details of the most recent price migration that failed for the subscription.



966
967
968
 
# File 'lib/stripe/resources/subscription.rb', line 966

def last_price_migration_error
  @last_price_migration_error
end

#latest_invoice ⇒ Object (readonly)

The most recent invoice this subscription has generated over its lifecycle (for example, when it cycles or is updated).



968
969
970
 
# File 'lib/stripe/resources/subscription.rb', line 968

def latest_invoice
  @latest_invoice
end

#livemode ⇒ Object (readonly)

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.



970
971
972
 
# File 'lib/stripe/resources/subscription.rb', line 970

def livemode
  @livemode
end

#managed_payments ⇒ Object (readonly)

Settings for Managed Payments for this Subscription and resulting Invoices and PaymentIntents.



972
973
974
 
# File 'lib/stripe/resources/subscription.rb', line 972

def managed_payments
  @managed_payments
end

#metadata ⇒ Object (readonly)

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.



974
975
976
 
# File 'lib/stripe/resources/subscription.rb', line 974

def metadata
  @metadata
end

#next_pending_invoice_item_invoice ⇒ Object (readonly)

Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at pending_invoice_item_interval.



976
977
978
 
# File 'lib/stripe/resources/subscription.rb', line 976

def next_pending_invoice_item_invoice
  @next_pending_invoice_item_invoice
end

#object ⇒ Object (readonly)

String representing the object's type. Objects of the same type share the same value.



978
979
980
 
# File 'lib/stripe/resources/subscription.rb', line 978

def object
  @object
end

#on_behalf_of ⇒ Object (readonly)

The account (if any) the charge was made on behalf of for charges associated with this subscription. See the Connect documentation for details.



980
981
982
 
# File 'lib/stripe/resources/subscription.rb', line 980

def on_behalf_of
  @on_behalf_of
end

#pause_collection ⇒ Object (readonly)

If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to paused. Learn more about pausing collection.



982
983
984
 
# File 'lib/stripe/resources/subscription.rb', line 982

def pause_collection
  @pause_collection
end

#payment_settings ⇒ Object (readonly)

Payment settings passed on to invoices created by the subscription.



984
985
986
 
# File 'lib/stripe/resources/subscription.rb', line 984

def payment_settings
  @payment_settings
end

#pending_invoice_item_interval ⇒ Object (readonly)

Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.



986
987
988
 
# File 'lib/stripe/resources/subscription.rb', line 986

def pending_invoice_item_interval
  @pending_invoice_item_interval
end

#pending_setup_intent ⇒ Object (readonly)

You can use this SetupIntent to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments. Learn more in the SCA Migration Guide.



988
989
990
 
# File 'lib/stripe/resources/subscription.rb', line 988

def pending_setup_intent
  @pending_setup_intent
end

#pending_update ⇒ Object (readonly)

If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid.



990
991
992
 
# File 'lib/stripe/resources/subscription.rb', line 990

def pending_update
  @pending_update
end

#prebilling ⇒ Object (readonly)

Time period and invoice for a Subscription billed in advance.



992
993
994
 
# File 'lib/stripe/resources/subscription.rb', line 992

def prebilling
  @prebilling
end

#presentment_details ⇒ Object (readonly)

Attribute for field presentment_details



994
995
996
 
# File 'lib/stripe/resources/subscription.rb', line 994

def presentment_details
  @presentment_details
end

#schedule ⇒ Object (readonly)

The schedule attached to the subscription



996
997
998
 
# File 'lib/stripe/resources/subscription.rb', line 996

def schedule
  @schedule
end

#start_date ⇒ Object (readonly)

Date when the subscription was first created. The date might differ from the created date due to backdating.



998
999
1000
 
# File 'lib/stripe/resources/subscription.rb', line 998

def start_date
  @start_date
end

#status ⇒ Object (readonly)

Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, or paused.

For collection_method=charge_automatically a subscription moves into incomplete if the initial payment attempt fails. A subscription in this status can only have metadata and default_source updated. Once the first invoice is paid, the subscription moves into an active status. If the first invoice is not paid within 23 hours, the subscription transitions to incomplete_expired. This is a terminal status, the open invoice will be voided and no further invoices will be generated.

A subscription that is currently in a trial period is trialing and moves to active when the trial period is over.

A subscription can only enter a paused status when a trial ends without a payment method. A paused subscription doesn't generate invoices and can be resumed after your customer adds their payment method. The paused status is different from pausing collection, which still generates invoices and leaves the subscription's status unchanged.

If subscription collection_method=charge_automatically, it becomes past_due when payment is required but cannot be paid (due to failed payment or awaiting additional user actions). Once Stripe has exhausted all payment retry attempts, the subscription will become canceled or unpaid (depending on your subscriptions settings).

If subscription collection_method=send_invoice it becomes past_due when its invoice is not paid by the due date, and canceled or unpaid if it is still not paid by an additional deadline after that. Note that when a subscription has a status of unpaid, no subsequent invoices will be attempted (invoices will be created, but then immediately automatically closed). After receiving updated payment information from a customer, you may choose to reopen and pay their closed invoices.



1010
1011
1012
 
# File 'lib/stripe/resources/subscription.rb', line 1010

def status
  @status
end

#status_details ⇒ Object (readonly)

Describes changes to the subscription's status.



1012
1013
1014
 
# File 'lib/stripe/resources/subscription.rb', line 1012

def status_details
  @status_details
end

#test_clock ⇒ Object (readonly)

ID of the test clock this subscription belongs to.



1014
1015
1016
 
# File 'lib/stripe/resources/subscription.rb', line 1014

def test_clock
  @test_clock
end

#transfer_data ⇒ Object (readonly)

The account (if any) the subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices.



1016
1017
1018
 
# File 'lib/stripe/resources/subscription.rb', line 1016

def transfer_data
  @transfer_data
end

#trial_end ⇒ Object (readonly)

If the subscription has a trial, the end of that trial.



1018
1019
1020
 
# File 'lib/stripe/resources/subscription.rb', line 1018

def trial_end
  @trial_end
end

#trial_settings ⇒ Object (readonly)

Settings related to subscription trials.



1020
1021
1022
 
# File 'lib/stripe/resources/subscription.rb', line 1020

def trial_settings
  @trial_settings
end

#trial_start ⇒ Object (readonly)

If the subscription has a trial, the beginning of that trial.



1022
1023
1024
 
# File 'lib/stripe/resources/subscription.rb', line 1022

def trial_start
  @trial_start
end

Class Method Details

.attach_cadence(subscription, params = {}, opts = {}) ⇒ Object

Attach a Billing Cadence to an existing subscription. When attached, the subscription is billed by the Billing Cadence, potentially sharing invoices with the other subscriptions linked to the Billing Cadence.



1035
1036
1037
1038
1039
1040
1041
1042
 
# File 'lib/stripe/resources/subscription.rb', line 1035

def self.attach_cadence(subscription, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/attach_cadence", { subscription: CGI.escape(subscription) }),
    params: params,
    opts: opts
  )
end

.cancel(subscription_exposed_id, params = {}, opts = {}) ⇒ Object

Cancels a customer's subscription immediately. The customer won't be charged again for the subscription. After it's canceled, the subscription is largely immutable. You can still update its metadata and cancellation_details.

Any pending invoice items that you've created are still charged 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 are also left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations are removed if invoice_now and prorate are both set to false.

By default, upon subscription cancellation, Stripe stops 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.



1063
1064
1065
1066
1067
1068
1069
1070
 
# File 'lib/stripe/resources/subscription.rb', line 1063

def self.cancel(subscription_exposed_id, params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/subscriptions/%<subscription_exposed_id>s", { subscription_exposed_id: CGI.escape(subscription_exposed_id) }),
    params: params,
    opts: opts
  )
end

.create(params = {}, opts = {}) ⇒ Object

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.



1079
1080
1081
 
# File 'lib/stripe/resources/subscription.rb', line 1079

def self.create(params = {}, opts = {})
  request_stripe_object(method: :post, path: "/v1/subscriptions", params: params, opts: opts)
end

.delete_discount(subscription_exposed_id, params = {}, opts = {}) ⇒ Object

Removes the currently applied discount on a subscription.



1094
1095
1096
1097
1098
1099
1100
1101
 
# File 'lib/stripe/resources/subscription.rb', line 1094

def self.delete_discount(subscription_exposed_id, params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/subscriptions/%<subscription_exposed_id>s/discount", { subscription_exposed_id: CGI.escape(subscription_exposed_id) }),
    params: params,
    opts: opts
  )
end

.field_remappings ⇒ Object 



1236
1237
1238
 
# File 'lib/stripe/resources/subscription.rb', line 1236

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
 
# File 'lib/stripe/resources/subscription.rb', line 1213

def self.inner_class_types
  @inner_class_types = {
    automatic_tax: AutomaticTax,
    billing_cycle_anchor_config: BillingCycleAnchorConfig,
    billing_mode: BillingMode,
    billing_schedules: BillingSchedule,
    billing_thresholds: BillingThresholds,
    cancellation_details: CancellationDetails,
    invoice_settings: InvoiceSettings,
    last_price_migration_error: LastPriceMigrationError,
    managed_payments: ManagedPayments,
    pause_collection: PauseCollection,
    payment_settings: PaymentSettings,
    pending_invoice_item_interval: PendingInvoiceItemInterval,
    pending_update: PendingUpdate,
    prebilling: Prebilling,
    presentment_details: PresentmentDetails,
    status_details: StatusDetails,
    transfer_data: TransferData,
    trial_settings: TrialSettings,
  }
end

.list(params = {}, opts = {}) ⇒ Object

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



1104
1105
1106
 
# File 'lib/stripe/resources/subscription.rb', line 1104

def self.list(params = {}, opts = {})
  request_stripe_object(method: :get, path: "/v1/subscriptions", params: params, opts: opts)
end

.migrate(subscription, params = {}, opts = {}) ⇒ Object

Upgrade the billing_mode of an existing subscription.



1119
1120
1121
1122
1123
1124
1125
1126
 
# File 'lib/stripe/resources/subscription.rb', line 1119

def self.migrate(subscription, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/migrate", { subscription: CGI.escape(subscription) }),
    params: params,
    opts: opts
  )
end

.object_name ⇒ Object 



15
16
17
 
# File 'lib/stripe/resources/subscription.rb', line 15

def self.object_name
  "subscription"
end

.pause(subscription, params = {}, opts = {}) ⇒ Object

Pauses a subscription by transitioning it to the paused status. A paused subscription does not generate invoices and will not advance to new billing periods. The subscription can be resumed later using the resume endpoint. Cannot pause subscriptions with attached schedules.



1139
1140
1141
1142
1143
1144
1145
1146
 
# File 'lib/stripe/resources/subscription.rb', line 1139

def self.pause(subscription, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/pause", { subscription: CGI.escape(subscription) }),
    params: params,
    opts: opts
  )
end

.resume(subscription, params = {}, opts = {}) ⇒ Object

Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. Resume is only available for subscriptions that use charge_automatically collection. If Stripe doesn't generate a resumption invoice, the subscription becomes active immediately. When a resumption invoice is generated, Stripe finalizes it immediately. If the invoice is paid or marked uncollectible, the subscription becomes active. If the invoice is manually voided, the subscription stays paused. If there is no payment attempt within 23 hours, Stripe voids the invoice and the subscription stays paused. Learn more about resuming subscriptions.



1159
1160
1161
1162
1163
1164
1165
1166
 
# File 'lib/stripe/resources/subscription.rb', line 1159

def self.resume(subscription, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/resume", { subscription: CGI.escape(subscription) }),
    params: params,
    opts: opts
  )
end

.search(params = {}, opts = {}) ⇒ Object 



1168
1169
1170
1171
1172
1173
1174
1175
 
# File 'lib/stripe/resources/subscription.rb', line 1168

def self.search(params = {}, opts = {})
  request_stripe_object(
    method: :get,
    path: "/v1/subscriptions/search",
    params: params,
    opts: opts
  )
end

.search_auto_paging_each(params = {}, opts = {}, &blk) ⇒ Object 



1177
1178
1179
 
# File 'lib/stripe/resources/subscription.rb', line 1177

def self.search_auto_paging_each(params = {}, opts = {}, &blk)
  search(params, opts).auto_paging_each(&blk)
end

.update(subscription_exposed_id, params = {}, opts = {}) ⇒ Object

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. You can also [use scripts to prorate your billing. To learn more, see Prorations](https://docs.stripe.com/billing/scripts/stripe-authored/proration).

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](https://docs.stripe.com/docs/rate-limits) instead.



1202
1203
1204
1205
1206
1207
1208
1209
 
# File 'lib/stripe/resources/subscription.rb', line 1202

def self.update(subscription_exposed_id, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription_exposed_id>s", { subscription_exposed_id: CGI.escape(subscription_exposed_id) }),
    params: params,
    opts: opts
  )
end

Instance Method Details

#attach_cadence(params = {}, opts = {}) ⇒ Object

Attach a Billing Cadence to an existing subscription. When attached, the subscription is billed by the Billing Cadence, potentially sharing invoices with the other subscriptions linked to the Billing Cadence.



1025
1026
1027
1028
1029
1030
1031
1032
 
# File 'lib/stripe/resources/subscription.rb', line 1025

def attach_cadence(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/attach_cadence", { subscription: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#cancel(params = {}, opts = {}) ⇒ Object

Cancels a customer's subscription immediately. The customer won't be charged again for the subscription. After it's canceled, the subscription is largely immutable. You can still update its metadata and cancellation_details.

Any pending invoice items that you've created are still charged 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 are also left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations are removed if invoice_now and prorate are both set to false.

By default, upon subscription cancellation, Stripe stops 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.



1049
1050
1051
1052
1053
1054
1055
1056
 
# File 'lib/stripe/resources/subscription.rb', line 1049

def cancel(params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/subscriptions/%<subscription_exposed_id>s", { subscription_exposed_id: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#delete_discount(params = {}, opts = {}) ⇒ Object

Removes the currently applied discount on a subscription.



1084
1085
1086
1087
1088
1089
1090
1091
 
# File 'lib/stripe/resources/subscription.rb', line 1084

def delete_discount(params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/subscriptions/%<subscription_exposed_id>s/discount", { subscription_exposed_id: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#migrate(params = {}, opts = {}) ⇒ Object

Upgrade the billing_mode of an existing subscription.



1109
1110
1111
1112
1113
1114
1115
1116
 
# File 'lib/stripe/resources/subscription.rb', line 1109

def migrate(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/migrate", { subscription: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#pause(params = {}, opts = {}) ⇒ Object

Pauses a subscription by transitioning it to the paused status. A paused subscription does not generate invoices and will not advance to new billing periods. The subscription can be resumed later using the resume endpoint. Cannot pause subscriptions with attached schedules.



1129
1130
1131
1132
1133
1134
1135
1136
 
# File 'lib/stripe/resources/subscription.rb', line 1129

def pause(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/pause", { subscription: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#resume(params = {}, opts = {}) ⇒ Object

Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. Resume is only available for subscriptions that use charge_automatically collection. If Stripe doesn't generate a resumption invoice, the subscription becomes active immediately. When a resumption invoice is generated, Stripe finalizes it immediately. If the invoice is paid or marked uncollectible, the subscription becomes active. If the invoice is manually voided, the subscription stays paused. If there is no payment attempt within 23 hours, Stripe voids the invoice and the subscription stays paused. Learn more about resuming subscriptions.



1149
1150
1151
1152
1153
1154
1155
1156
 
# File 'lib/stripe/resources/subscription.rb', line 1149

def resume(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/subscriptions/%<subscription>s/resume", { subscription: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end