Package com.stripe.model

Class Subscription

java.lang.Object
com.stripe.model.StripeObject
com.stripe.net.ApiResource
com.stripe.model.Subscription
All Implemented Interfaces:
HasId, MetadataStore<Subscription>, StripeActiveObject, StripeObjectInterface
public class Subscription extends ApiResource implements HasId, MetadataStore<Subscription>
Subscriptions allow you to charge a customer on a recurring basis.

Related guide: Creating subscriptions

  • Constructor Details

    • Subscription

      public Subscription()

  • Method Details

    • getApplication

      public String getApplication()
      Get ID of expandable application object.

    • setApplication

      public void setApplication(String id)

    • getApplicationObject

      public Application getApplicationObject()
      Get expanded application.

    • setApplicationObject

      public void setApplicationObject(Application expandableObject)

    • getCustomer

      public String getCustomer()
      Get ID of expandable customer object.

    • setCustomer

      public void setCustomer(String id)

    • getCustomerObject

      public Customer getCustomerObject()
      Get expanded customer.

    • setCustomerObject

      public void setCustomerObject(Customer expandableObject)

    • getDefaultPaymentMethod

      public String getDefaultPaymentMethod()
      Get ID of expandable defaultPaymentMethod object.

    • setDefaultPaymentMethod

      public void setDefaultPaymentMethod(String id)

    • getDefaultPaymentMethodObject

      public PaymentMethod getDefaultPaymentMethodObject()
      Get expanded defaultPaymentMethod.

    • setDefaultPaymentMethodObject

      public void setDefaultPaymentMethodObject(PaymentMethod expandableObject)

    • getDefaultSource

      public String getDefaultSource()
      Get ID of expandable defaultSource object.

    • setDefaultSource

      public void setDefaultSource(String id)

    • getDefaultSourceObject

      public PaymentSource getDefaultSourceObject()
      Get expanded defaultSource.

    • setDefaultSourceObject

      public void setDefaultSourceObject(PaymentSource expandableObject)

    • getLatestInvoice

      public String getLatestInvoice()
      Get ID of expandable latestInvoice object.

    • setLatestInvoice

      public void setLatestInvoice(String id)

    • getLatestInvoiceObject

      public Invoice getLatestInvoiceObject()
      Get expanded latestInvoice.

    • setLatestInvoiceObject

      public void setLatestInvoiceObject(Invoice expandableObject)

    • getOnBehalfOf

      public String getOnBehalfOf()
      Get ID of expandable onBehalfOf object.

    • setOnBehalfOf

      public void setOnBehalfOf(String id)

    • getOnBehalfOfObject

      public Account getOnBehalfOfObject()
      Get expanded onBehalfOf.

    • setOnBehalfOfObject

      public void setOnBehalfOfObject(Account expandableObject)

    • getPendingSetupIntent

      public String getPendingSetupIntent()
      Get ID of expandable pendingSetupIntent object.

    • setPendingSetupIntent

      public void setPendingSetupIntent(String id)

    • getPendingSetupIntentObject

      public SetupIntent getPendingSetupIntentObject()
      Get expanded pendingSetupIntent.

    • setPendingSetupIntentObject

      public void setPendingSetupIntentObject(SetupIntent expandableObject)

    • getSchedule

      public String getSchedule()
      Get ID of expandable schedule object.

    • setSchedule

      public void setSchedule(String id)

    • getScheduleObject

      public SubscriptionSchedule getScheduleObject()
      Get expanded schedule.

    • setScheduleObject

      public void setScheduleObject(SubscriptionSchedule expandableObject)

    • getTestClock

      public String getTestClock()
      Get ID of expandable testClock object.

    • setTestClock

      public void setTestClock(String id)

    • getTestClockObject

      public TestClock getTestClockObject()
      Get expanded testClock.

    • setTestClockObject

      public void setTestClockObject(TestClock expandableObject)

    • getDiscounts

      public List<String> getDiscounts()
      Get IDs of expandable discounts object list.

    • setDiscounts

      public void setDiscounts(List<String> ids)

    • getDiscountObjects

      public List<Discount> getDiscountObjects()
      Get expanded discounts.

    • setDiscountObjects

      public void setDiscountObjects(List<Discount> objs)

    • attachCadence

      public Subscription attachCadence(Map<String,Object> params) throws StripeException
      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.
      Throws:
      StripeException

    • attachCadence

      public Subscription attachCadence(Map<String,Object> params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • attachCadence

      public Subscription attachCadence(SubscriptionAttachCadenceParams params) throws StripeException
      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.
      Throws:
      StripeException

    • attachCadence

      public Subscription attachCadence(SubscriptionAttachCadenceParams params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • cancel

      public Subscription cancel() throws StripeException
      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.

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

      Throws:
      StripeException

    • cancel

      public Subscription cancel(Map<String,Object> params) throws StripeException
      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.

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

      Throws:
      StripeException

    • cancel

      public Subscription cancel(Map<String,Object> params, RequestOptions options) throws StripeException
      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.

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

      Throws:
      StripeException

    • cancel

      public Subscription cancel(SubscriptionCancelParams params) throws StripeException
      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.

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

      Throws:
      StripeException

    • cancel

      public Subscription cancel(SubscriptionCancelParams params, RequestOptions options) throws StripeException
      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.

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

      Throws:
      StripeException

    • create

      public static Subscription create(Map<String,Object> params) throws StripeException
      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.

      Throws:
      StripeException

    • create

      public static Subscription create(Map<String,Object> params, RequestOptions options) throws StripeException
      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.

      Throws:
      StripeException

    • create

      public static Subscription create(SubscriptionCreateParams params) throws StripeException
      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.

      Throws:
      StripeException

    • create

      public static Subscription create(SubscriptionCreateParams params, RequestOptions options) throws StripeException
      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.

      Throws:
      StripeException

    • deleteDiscount

      public Discount deleteDiscount() throws StripeException
      Removes the currently applied discount on a subscription.
      Throws:
      StripeException

    • deleteDiscount

      public Discount deleteDiscount(Map<String,Object> params) throws StripeException
      Removes the currently applied discount on a subscription.
      Throws:
      StripeException

    • deleteDiscount

      public Discount deleteDiscount(Map<String,Object> params, RequestOptions options) throws StripeException
      Removes the currently applied discount on a subscription.
      Throws:
      StripeException

    • list

      public static SubscriptionCollection list(Map<String,Object> params) throws StripeException
      By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
      Throws:
      StripeException

    • list

      public static SubscriptionCollection list(Map<String,Object> params, RequestOptions options) throws StripeException
      By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
      Throws:
      StripeException

    • list

      public static SubscriptionCollection list(SubscriptionListParams params) throws StripeException
      By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
      Throws:
      StripeException

    • list

      public static SubscriptionCollection list(SubscriptionListParams params, RequestOptions options) throws StripeException
      By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
      Throws:
      StripeException

    • migrate

      public Subscription migrate(Map<String,Object> params) throws StripeException
      Upgrade the billing_mode of an existing subscription.
      Throws:
      StripeException

    • migrate

      public Subscription migrate(Map<String,Object> params, RequestOptions options) throws StripeException
      Upgrade the billing_mode of an existing subscription.
      Throws:
      StripeException

    • migrate

      public Subscription migrate(SubscriptionMigrateParams params) throws StripeException
      Upgrade the billing_mode of an existing subscription.
      Throws:
      StripeException

    • migrate

      public Subscription migrate(SubscriptionMigrateParams params, RequestOptions options) throws StripeException
      Upgrade the billing_mode of an existing subscription.
      Throws:
      StripeException

    • resume

      public Subscription resume() throws StripeException
      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.
      Throws:
      StripeException

    • resume

      public Subscription resume(RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • resume

      public Subscription resume(Map<String,Object> params) throws StripeException
      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.
      Throws:
      StripeException

    • resume

      public Subscription resume(Map<String,Object> params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • resume

      public Subscription resume(SubscriptionResumeParams params) throws StripeException
      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.
      Throws:
      StripeException

    • resume

      public Subscription resume(SubscriptionResumeParams params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • retrieve

      public static Subscription retrieve(String subscriptionExposedId) throws StripeException
      Retrieves the subscription with the given ID.
      Throws:
      StripeException

    • retrieve

      public static Subscription retrieve(String subscriptionExposedId, RequestOptions options) throws StripeException
      Retrieves the subscription with the given ID.
      Throws:
      StripeException

    • retrieve

      public static Subscription retrieve(String subscriptionExposedId, Map<String,Object> params, RequestOptions options) throws StripeException
      Retrieves the subscription with the given ID.
      Throws:
      StripeException

    • retrieve

      public static Subscription retrieve(String subscriptionExposedId, SubscriptionRetrieveParams params, RequestOptions options) throws StripeException
      Retrieves the subscription with the given ID.
      Throws:
      StripeException

    • search

      public static SubscriptionSearchResult search(Map<String,Object> params) throws StripeException
      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.
      Throws:
      StripeException

    • search

      public static SubscriptionSearchResult search(Map<String,Object> params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • search

      public static SubscriptionSearchResult search(SubscriptionSearchParams params) throws StripeException
      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.
      Throws:
      StripeException

    • search

      public static SubscriptionSearchResult search(SubscriptionSearchParams params, RequestOptions options) throws StripeException
      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.
      Throws:
      StripeException

    • update

      public Subscription update(Map<String,Object> params) throws StripeException
      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.

      Specified by:
      update in interface MetadataStore<Subscription>
      Throws:
      StripeException

    • update

      public Subscription update(Map<String,Object> params, RequestOptions options) throws StripeException
      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.

      Specified by:
      update in interface MetadataStore<Subscription>
      Throws:
      StripeException

    • update

      public Subscription update(SubscriptionUpdateParams params) throws StripeException
      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.

      Throws:
      StripeException

    • update

      public Subscription update(SubscriptionUpdateParams params, RequestOptions options) throws StripeException
      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.

      Throws:
      StripeException

    • setResponseGetter

      public void setResponseGetter(StripeResponseGetter responseGetter)
      Indicates how the subscription should change when the trial ends if the user did not provide a payment method.

      One of cancel, create_invoice, or pause.

      Specified by:
      setResponseGetter in interface StripeActiveObject
      Overrides:
      setResponseGetter in class ApiResource
      Parameters:
      responseGetter - the StripeResponseGetter instance to use for making further requests.

    • getApplicationFeePercent

      public BigDecimal getApplicationFeePercent()
      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.

    • getAutomaticTax

      public Subscription.AutomaticTax getAutomaticTax()

    • getBillingCadence

      public String getBillingCadence()
      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.

    • getBillingCycleAnchor

      public Long getBillingCycleAnchor()
      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.

    • getBillingCycleAnchorConfig

      public Subscription.BillingCycleAnchorConfig getBillingCycleAnchorConfig()
      The fixed values used to calculate the billing_cycle_anchor.

    • getBillingMode

      public Subscription.BillingMode getBillingMode()
      The billing mode of the subscription.

    • getBillingSchedules

      public List<Subscription.BillingSchedule> getBillingSchedules()
      Billing schedules for this subscription.

    • getBillingThresholds

      public Subscription.BillingThresholds getBillingThresholds()
      Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period.

    • getCancelAt

      public Long getCancelAt()
      A date in the future at which the subscription will automatically get canceled.

    • getCancelAtPeriodEnd

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

    • getCanceledAt

      public Long getCanceledAt()
      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.

    • getCancellationDetails

      public Subscription.CancellationDetails getCancellationDetails()
      Details about why this subscription was cancelled.

    • getCollectionMethod

      public String getCollectionMethod()
      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.

      One of charge_automatically, or send_invoice.

    • getCreated

      public Long getCreated()
      Time at which the object was created. Measured in seconds since the Unix epoch.

    • getCurrency

      public String getCurrency()
      Three-letter ISO currency code, in lowercase. Must be a supported currency.

    • getCustomerAccount

      public String getCustomerAccount()
      ID of the account who owns the subscription.

    • getDaysUntilDue

      public Long getDaysUntilDue()
      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.

    • getDefaultTaxRates

      public List<TaxRate> getDefaultTaxRates()
      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.

    • getDescription

      public String getDescription()
      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.

    • getEndedAt

      public Long getEndedAt()
      If the subscription has ended, the date the subscription ended.

    • getInvoiceSettings

      public Subscription.InvoiceSettings getInvoiceSettings()

    • getItems

      public SubscriptionItemCollection getItems()
      List of subscription items, each with an attached price.

    • getLastPriceMigrationError

      public Subscription.LastPriceMigrationError getLastPriceMigrationError()
      Details of the most recent price migration that failed for the subscription.

    • getLivemode

      public Boolean getLivemode()
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.

    • getNextPendingInvoiceItemInvoice

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

    • getObject

      public String getObject()
      String representing the object's type. Objects of the same type share the same value.

      Equal to subscription.

    • getPauseCollection

      public Subscription.PauseCollection getPauseCollection()
      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.

    • getPaymentSettings

      public Subscription.PaymentSettings getPaymentSettings()
      Payment settings passed on to invoices created by the subscription.

    • getPendingInvoiceItemInterval

      public Subscription.PendingInvoiceItemInterval getPendingInvoiceItemInterval()
      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.

    • getPendingUpdate

      public Subscription.PendingUpdate getPendingUpdate()
      If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid.

    • getPrebilling

      public Subscription.Prebilling getPrebilling()
      Time period and invoice for a Subscription billed in advance.

    • getStartDate

      public Long getStartDate()
      Date when the subscription was first created. The date might differ from the created date due to backdating.

    • getStatus

      public String getStatus()
      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.

      One of active, canceled, incomplete, incomplete_expired, past_due, paused, trialing, or unpaid.

    • getTransferData

      public Subscription.TransferData getTransferData()
      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.

    • getTrialEnd

      public Long getTrialEnd()
      If the subscription has a trial, the end of that trial.

    • getTrialSettings

      public Subscription.TrialSettings getTrialSettings()
      Settings related to subscription trials.

    • getTrialStart

      public Long getTrialStart()
      If the subscription has a trial, the beginning of that trial.

    • setApplicationFeePercent

      public void setApplicationFeePercent(BigDecimal applicationFeePercent)
      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.

    • setAutomaticTax

      public void setAutomaticTax(Subscription.AutomaticTax automaticTax)

    • setBillingCadence

      public void setBillingCadence(String billingCadence)
      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.

    • setBillingCycleAnchor

      public void setBillingCycleAnchor(Long billingCycleAnchor)
      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.

    • setBillingCycleAnchorConfig

      public void setBillingCycleAnchorConfig(Subscription.BillingCycleAnchorConfig billingCycleAnchorConfig)
      The fixed values used to calculate the billing_cycle_anchor.

    • setBillingMode

      public void setBillingMode(Subscription.BillingMode billingMode)
      The billing mode of the subscription.

    • setBillingSchedules

      public void setBillingSchedules(List<Subscription.BillingSchedule> billingSchedules)
      Billing schedules for this subscription.

    • setBillingThresholds

      public void setBillingThresholds(Subscription.BillingThresholds billingThresholds)
      Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period.

    • setCancelAt

      public void setCancelAt(Long cancelAt)
      A date in the future at which the subscription will automatically get canceled.

    • setCancelAtPeriodEnd

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

    • setCanceledAt

      public void setCanceledAt(Long canceledAt)
      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.

    • setCancellationDetails

      public void setCancellationDetails(Subscription.CancellationDetails cancellationDetails)
      Details about why this subscription was cancelled.

    • setCollectionMethod

      public void setCollectionMethod(String collectionMethod)
      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.

      One of charge_automatically, or send_invoice.

    • setCreated

      public void setCreated(Long created)
      Time at which the object was created. Measured in seconds since the Unix epoch.

    • setCurrency

      public void setCurrency(String currency)
      Three-letter ISO currency code, in lowercase. Must be a supported currency.

    • setCustomerAccount

      public void setCustomerAccount(String customerAccount)
      ID of the account who owns the subscription.

    • setDaysUntilDue

      public void setDaysUntilDue(Long daysUntilDue)
      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.

    • setDefaultTaxRates

      public void setDefaultTaxRates(List<TaxRate> defaultTaxRates)
      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.

    • setDescription

      public void setDescription(String description)
      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.

    • setEndedAt

      public void setEndedAt(Long endedAt)
      If the subscription has ended, the date the subscription ended.

    • setId

      public void setId(String id)
      Unique identifier for the object.

    • setInvoiceSettings

      public void setInvoiceSettings(Subscription.InvoiceSettings invoiceSettings)

    • setItems

      public void setItems(SubscriptionItemCollection items)
      List of subscription items, each with an attached price.

    • setLastPriceMigrationError

      public void setLastPriceMigrationError(Subscription.LastPriceMigrationError lastPriceMigrationError)
      Details of the most recent price migration that failed for the subscription.

    • setLivemode

      public void setLivemode(Boolean livemode)
      Has the value true if the object exists in live mode or the value false if the object exists in test mode.

    • setMetadata

      public void setMetadata(Map<String,String> metadata)
      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.

    • setNextPendingInvoiceItemInvoice

      public void setNextPendingInvoiceItemInvoice(Long nextPendingInvoiceItemInvoice)
      Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at pending_invoice_item_interval.

    • setObject

      public void setObject(String object)
      String representing the object's type. Objects of the same type share the same value.

      Equal to subscription.

    • setPauseCollection

      public void setPauseCollection(Subscription.PauseCollection pauseCollection)
      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.

    • setPaymentSettings

      public void setPaymentSettings(Subscription.PaymentSettings paymentSettings)
      Payment settings passed on to invoices created by the subscription.

    • setPendingInvoiceItemInterval

      public void setPendingInvoiceItemInterval(Subscription.PendingInvoiceItemInterval pendingInvoiceItemInterval)
      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.

    • setPendingUpdate

      public void setPendingUpdate(Subscription.PendingUpdate pendingUpdate)
      If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid.

    • setPrebilling

      public void setPrebilling(Subscription.Prebilling prebilling)
      Time period and invoice for a Subscription billed in advance.

    • setStartDate

      public void setStartDate(Long startDate)
      Date when the subscription was first created. The date might differ from the created date due to backdating.

    • setStatus

      public void setStatus(String status)
      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.

      One of active, canceled, incomplete, incomplete_expired, past_due, paused, trialing, or unpaid.

    • setTransferData

      public void setTransferData(Subscription.TransferData transferData)
      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.

    • setTrialEnd

      public void setTrialEnd(Long trialEnd)
      If the subscription has a trial, the end of that trial.

    • setTrialSettings

      public void setTrialSettings(Subscription.TrialSettings trialSettings)
      Settings related to subscription trials.

    • setTrialStart

      public void setTrialStart(Long trialStart)
      If the subscription has a trial, the beginning of that trial.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getId

      public String getId()
      Unique identifier for the object.
      Specified by:
      getId in interface HasId

    • getMetadata

      public Map<String,String> getMetadata()
      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.
      Specified by:
      getMetadata in interface MetadataStore<Subscription>