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](stripe.com/docs/billing/subscriptions/creating)

Defined Under Namespace

Classes: AttachCadenceParams, AutomaticTax, BillingCycleAnchorConfig, BillingMode, BillingThresholds, CancelParams, CancellationDetails, CreateParams, DeleteDiscountParams, InvoiceSettings, LastPriceMigrationError, ListParams, MigrateParams, PauseCollection, PaymentSettings, PendingInvoiceItemInterval, PendingUpdate, Prebilling, ResumeParams, SearchParams, TransferData, TrialSettings, UpdateParams

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?, #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.



2465
2466
2467
 
# File 'lib/stripe/resources/subscription.rb', line 2465

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.



2467
2468
2469
 
# File 'lib/stripe/resources/subscription.rb', line 2467

def application_fee_percent
  @application_fee_percent
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



2469
2470
2471
 
# File 'lib/stripe/resources/subscription.rb', line 2469

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.



2471
2472
2473
 
# File 'lib/stripe/resources/subscription.rb', line 2471

def billing_cadence
  @billing_cadence
end

#billing_cycle_anchor ⇒ Object (readonly)

The reference point that aligns future [billing cycle](stripe.com/docs/subscriptions/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.



2473
2474
2475
 
# File 'lib/stripe/resources/subscription.rb', line 2473

def billing_cycle_anchor
  @billing_cycle_anchor
end

#billing_cycle_anchor_config ⇒ Object (readonly)

The fixed values used to calculate the ‘billing_cycle_anchor`.



2475
2476
2477
 
# File 'lib/stripe/resources/subscription.rb', line 2475

def billing_cycle_anchor_config
  @billing_cycle_anchor_config
end

#billing_mode ⇒ Object (readonly)

The billing mode of the subscription.



2477
2478
2479
 
# File 'lib/stripe/resources/subscription.rb', line 2477

def billing_mode
  @billing_mode
end

#billing_thresholds ⇒ Object (readonly)

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



2479
2480
2481
 
# File 'lib/stripe/resources/subscription.rb', line 2479

def billing_thresholds
  @billing_thresholds
end

#cancel_at ⇒ Object (readonly)

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



2481
2482
2483
 
# File 'lib/stripe/resources/subscription.rb', line 2481

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.



2483
2484
2485
 
# File 'lib/stripe/resources/subscription.rb', line 2483

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.



2485
2486
2487
 
# File 'lib/stripe/resources/subscription.rb', line 2485

def canceled_at
  @canceled_at
end

#cancellation_details ⇒ Object (readonly)

Details about why this subscription was cancelled



2487
2488
2489
 
# File 'lib/stripe/resources/subscription.rb', line 2487

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`.



2489
2490
2491
 
# File 'lib/stripe/resources/subscription.rb', line 2489

def collection_method
  @collection_method
end

#created ⇒ Object (readonly)

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



2491
2492
2493
 
# File 'lib/stripe/resources/subscription.rb', line 2491

def created
  @created
end

#currency ⇒ Object (readonly)

Three-letter [ISO currency code](www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](stripe.com/docs/currencies).



2493
2494
2495
 
# File 'lib/stripe/resources/subscription.rb', line 2493

def currency
  @currency
end

#customer ⇒ Object (readonly)

ID of the customer who owns the subscription.



2495
2496
2497
 
# File 'lib/stripe/resources/subscription.rb', line 2495

def customer
  @customer
end

#customer_account ⇒ Object (readonly)

ID of the account who owns the subscription.



2497
2498
2499
 
# File 'lib/stripe/resources/subscription.rb', line 2497

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`.



2499
2500
2501
 
# File 'lib/stripe/resources/subscription.rb', line 2499

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](stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](stripe.com/docs/api/customers/object#customer_object-default_source).



2501
2502
2503
 
# File 'lib/stripe/resources/subscription.rb', line 2501

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](stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) or [default_source](stripe.com/docs/api/customers/object#customer_object-default_source).



2503
2504
2505
 
# File 'lib/stripe/resources/subscription.rb', line 2503

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.



2505
2506
2507
 
# File 'lib/stripe/resources/subscription.rb', line 2505

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.



2507
2508
2509
 
# File 'lib/stripe/resources/subscription.rb', line 2507

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.



2509
2510
2511
 
# File 'lib/stripe/resources/subscription.rb', line 2509

def discounts
  @discounts
end

#ended_at ⇒ Object (readonly)

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



2511
2512
2513
 
# File 'lib/stripe/resources/subscription.rb', line 2511

def ended_at
  @ended_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



2513
2514
2515
 
# File 'lib/stripe/resources/subscription.rb', line 2513

def id
  @id
end

#invoice_settings ⇒ Object (readonly)

Attribute for field invoice_settings



2515
2516
2517
 
# File 'lib/stripe/resources/subscription.rb', line 2515

def invoice_settings
  @invoice_settings
end

#items ⇒ Object (readonly)

List of subscription items, each with an attached price.



2517
2518
2519
 
# File 'lib/stripe/resources/subscription.rb', line 2517

def items
  @items
end

#last_price_migration_error ⇒ Object (readonly)

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



2519
2520
2521
 
# File 'lib/stripe/resources/subscription.rb', line 2519

def last_price_migration_error
  @last_price_migration_error
end

#latest_invoice ⇒ Object (readonly)

The most recent invoice this subscription has generated.



2521
2522
2523
 
# File 'lib/stripe/resources/subscription.rb', line 2521

def latest_invoice
  @latest_invoice
end

#livemode ⇒ Object (readonly)

Has the value ‘true` if the object exists in live mode or the value `false` if the object exists in test mode.



2523
2524
2525
 
# File 'lib/stripe/resources/subscription.rb', line 2523

def livemode
  @livemode
end

#metadata ⇒ Object (readonly)

Set of [key-value pairs](stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.



2525
2526
2527
 
# File 'lib/stripe/resources/subscription.rb', line 2525

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`.



2527
2528
2529
 
# File 'lib/stripe/resources/subscription.rb', line 2527

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.



2529
2530
2531
 
# File 'lib/stripe/resources/subscription.rb', line 2529

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](stripe.com/docs/connect/subscriptions#on-behalf-of) for details.



2531
2532
2533
 
# File 'lib/stripe/resources/subscription.rb', line 2531

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](stripe.com/docs/billing/subscriptions/pause-payment).



2533
2534
2535
 
# File 'lib/stripe/resources/subscription.rb', line 2533

def pause_collection
  @pause_collection
end

#payment_settings ⇒ Object (readonly)

Payment settings passed on to invoices created by the subscription.



2535
2536
2537
 
# File 'lib/stripe/resources/subscription.rb', line 2535

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](stripe.com/docs/api#create_invoice) for the given subscription at the specified interval.



2537
2538
2539
 
# File 'lib/stripe/resources/subscription.rb', line 2537

def pending_invoice_item_interval
  @pending_invoice_item_interval
end

#pending_setup_intent ⇒ Object (readonly)

You can use this [SetupIntent](stripe.com/docs/api/setup_intents) 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](stripe.com/docs/billing/migration/strong-customer-authentication#scenario-2).



2539
2540
2541
 
# File 'lib/stripe/resources/subscription.rb', line 2539

def pending_setup_intent
  @pending_setup_intent
end

#pending_update ⇒ Object (readonly)

If specified, [pending updates](stripe.com/docs/billing/subscriptions/pending-updates) that will be applied to the subscription once the ‘latest_invoice` has been paid.



2541
2542
2543
 
# File 'lib/stripe/resources/subscription.rb', line 2541

def pending_update
  @pending_update
end

#prebilling ⇒ Object (readonly)

Time period and invoice for a Subscription billed in advance.



2543
2544
2545
 
# File 'lib/stripe/resources/subscription.rb', line 2543

def prebilling
  @prebilling
end

#schedule ⇒ Object (readonly)

The schedule attached to the subscription



2545
2546
2547
 
# File 'lib/stripe/resources/subscription.rb', line 2545

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.



2547
2548
2549
 
# File 'lib/stripe/resources/subscription.rb', line 2547

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](stripe.com/docs/billing/subscriptions/trials#create-free-trials-without-payment). 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](stripe.com/docs/billing/subscriptions/pause-payment), 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.



2559
2560
2561
 
# File 'lib/stripe/resources/subscription.rb', line 2559

def status
  @status
end

#test_clock ⇒ Object (readonly)

ID of the test clock this subscription belongs to.



2561
2562
2563
 
# File 'lib/stripe/resources/subscription.rb', line 2561

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.



2563
2564
2565
 
# File 'lib/stripe/resources/subscription.rb', line 2563

def transfer_data
  @transfer_data
end

#trial_end ⇒ Object (readonly)

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



2565
2566
2567
 
# File 'lib/stripe/resources/subscription.rb', line 2565

def trial_end
  @trial_end
end

#trial_settings ⇒ Object (readonly)

Settings related to subscription trials.



2567
2568
2569
 
# File 'lib/stripe/resources/subscription.rb', line 2567

def trial_settings
  @trial_settings
end

#trial_start ⇒ Object (readonly)

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



2569
2570
2571
 
# File 'lib/stripe/resources/subscription.rb', line 2569

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.



2582
2583
2584
2585
2586
2587
2588
2589
 
# File 'lib/stripe/resources/subscription.rb', line 2582

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, you can no longer update the subscription or its [metadata](docs.stripe.com/metadata).

Any pending invoice items that you’ve created are still charged at the end of the period, unless manually [deleted](docs.stripe.com/api#delete_invoiceitem). 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 true.

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.



2610
2611
2612
2613
2614
2615
2616
2617
 
# File 'lib/stripe/resources/subscription.rb', line 2610

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](docs.stripe.com/docs/billing/subscriptions/subscription-schedules#managing) instead. Schedules provide the flexibility to model more complex billing configurations that change over time.



2626
2627
2628
 
# File 'lib/stripe/resources/subscription.rb', line 2626

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.



2641
2642
2643
2644
2645
2646
2647
2648
 
# File 'lib/stripe/resources/subscription.rb', line 2641

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 



2759
2760
2761
 
# File 'lib/stripe/resources/subscription.rb', line 2759

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
 
# File 'lib/stripe/resources/subscription.rb', line 2740

def self.inner_class_types
  @inner_class_types = {
    automatic_tax: AutomaticTax,
    billing_cycle_anchor_config: BillingCycleAnchorConfig,
    billing_mode: BillingMode,
    billing_thresholds: BillingThresholds,
    cancellation_details: CancellationDetails,
    invoice_settings: InvoiceSettings,
    last_price_migration_error: LastPriceMigrationError,
    pause_collection: PauseCollection,
    payment_settings: PaymentSettings,
    pending_invoice_item_interval: PendingInvoiceItemInterval,
    pending_update: PendingUpdate,
    prebilling: Prebilling,
    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.



2651
2652
2653
 
# File 'lib/stripe/resources/subscription.rb', line 2651

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.



2666
2667
2668
2669
2670
2671
2672
2673
 
# File 'lib/stripe/resources/subscription.rb', line 2666

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

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

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.



2686
2687
2688
2689
2690
2691
2692
2693
 
# File 'lib/stripe/resources/subscription.rb', line 2686

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 



2695
2696
2697
2698
2699
2700
2701
2702
 
# File 'lib/stripe/resources/subscription.rb', line 2695

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 



2704
2705
2706
 
# File 'lib/stripe/resources/subscription.rb', line 2704

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](docs.stripe.com/docs/api/invoices/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](docs.stripe.com/docs/billing/subscriptions/upgrade-downgrade#immediate-payment).

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](docs.stripe.com/docs/api/invoices/create).

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 <a href=“/docs/billing/subscriptions/usage-based”>usage-based billing](docs.stripe.com/docs/rate-limits) instead.



2729
2730
2731
2732
2733
2734
2735
2736
 
# File 'lib/stripe/resources/subscription.rb', line 2729

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.



2572
2573
2574
2575
2576
2577
2578
2579
 
# File 'lib/stripe/resources/subscription.rb', line 2572

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, you can no longer update the subscription or its [metadata](docs.stripe.com/metadata).

Any pending invoice items that you’ve created are still charged at the end of the period, unless manually [deleted](docs.stripe.com/api#delete_invoiceitem). 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 true.

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.



2596
2597
2598
2599
2600
2601
2602
2603
 
# File 'lib/stripe/resources/subscription.rb', line 2596

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.



2631
2632
2633
2634
2635
2636
2637
2638
 
# File 'lib/stripe/resources/subscription.rb', line 2631

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.



2656
2657
2658
2659
2660
2661
2662
2663
 
# File 'lib/stripe/resources/subscription.rb', line 2656

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

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

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.



2676
2677
2678
2679
2680
2681
2682
2683
 
# File 'lib/stripe/resources/subscription.rb', line 2676

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