API upgrades
Your API version controls the API and webhook behavior you see (for example, what properties you see in responses, what parameters you’re permitted to send in requests, and so on). Your version gets set the first time you make an API request. When a breaking change is introduced to the Stripe API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.
If you make requests on behalf of other users using Connect, we’ll use your application’s API version, making it easy for you to write code that works for all your users no matter what API versions they’re individually running.
Backwards-compatible changes 
Stripe considers the following changes to be backwards-compatible:
- Adding new API resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
- Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
- This includes adding or removing fixed prefixes (such as
ch_on charge IDs). - Make sure that your integration can handle Stripe-generated object IDs, which can contain up to 255 characters. For example, if you’re using MySQL, store the IDs in a
VARCHAR(255) COLLATE utf8_bincolumn (theCOLLATEconfiguration provides case-sensitivity during lookups).
- This includes adding or removing fixed prefixes (such as
- Adding new event types.
- Make sure that your webhook listener gracefully handles unfamiliar event types.
Upgrade your API version 
If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses so the API is faster for you.
Upgrading your API version affects:
- The API calls you make without a
Stripe-Versionheader: the parameters you can send and the structure of objects returned. - The structure of objects received with Stripe.js methods such as confirmCardPayment.
- The structure of objects sent to your webhook endpoints (both Account and Connect ones.) If an endpoint has an explicit version set, it will remain unaffected.
- Automated Billing operations performed by Stripe (for example, generating an invoice for a new subscription period) use your account’s default API version. See the API changelog for details about how your default API version will impact these operations.
View your API version and the latest upgrade in the Dashboard
To see what version you’re running and the latest upgrade, visit your Developer Dashboard.
When performing an API upgrade, make sure that you specify the API version that you’re integrating against in your code instead of relying on your account’s default API version. To test a newer version for API calls, set the Stripe-Version header (in live or test mode). Learn how to manage versioning in our server-side libraries.
Upgrade and test your webhooks
For webhooks, you can override the version of a single test webhook endpoint in your Dashboard. To safely upgrade your webhooks, Stripe recommends that you:
- Check for breaking changes to see which objects will be structured differently.
- Update your webhook code to handle both the old and new version of each object.
- Change the version of a test webhook endpoint to the version you want to test.
- Trigger the event in test mode and validate that your code works for the new structure.
Finalize the upgrade
When you’re confident that your code can handle the latest API version, click the Upgrade version button in your Dashboard. This switches the version used by API calls that don’t have the Stripe-Version header and also switches the version used to render objects sent to your webhooks.
Caution
The shape of resources inside events retrieved from the API is defined by the default API version of your account at the time the event occurred. If your code retrieves events created when your default API version was different your code will need to account for these changes when processing events.
Roll back your API version
For 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in your Dashboard.
After you’ve rolled back, webhooks that were sent with the new object structure and failed will be retried with the old structure.
Stay informed
We send information on new additions and changes to Stripe’s API and language libraries in the Stripe Developer Digest. Be sure to subscribe to stay informed.
Sign up for the Developer Digest
API versions
Listed below are all the breaking changes to the Stripe API. Each date corresponds with a new version of the Stripe API. If you’re looking for all API additions and updates, see the API changelog. If you are looking for new product releases, see the product changelog.
2023-10-16
In the Accounts API, the following error codes have been added as new error codes in the
requirements.errorsarray. See Account requirements errors for more information.invalid_address_highway_contract_boxinvalid_address_private_mailboxinvalid_business_profile_nameinvalid_business_profile_name_denylistedinvalid_company_name_denylistedinvalid_dob_age_over_maximuminvalid_dob_age_under_minimuminvalid_product_description_lengthinvalid_product_description_url_matchinvalid_statement_descriptor_business_mismatchinvalid_statement_descriptor_denylistedinvalid_statement_descriptor_lengthinvalid_statement_descriptor_prefix_denylistedinvalid_statement_descriptor_prefix_mismatchinvalid_tax_id_formatinvalid_url_denylistedinvalid_url_formatinvalid_url_web_presence_detectedinvalid_url_website_business_information_mismatchinvalid_url_website_emptyinvalid_url_website_inaccessibleinvalid_url_website_inaccessible_geoblockedinvalid_url_website_inaccessible_password_protectedinvalid_url_website_incompleteinvalid_url_website_incomplete_cancellation_policyinvalid_url_website_incomplete_customer_service_detailsinvalid_url_website_incomplete_legal_restrictionsinvalid_url_website_incomplete_refund_policyinvalid_url_website_incomplete_return_policyinvalid_url_website_incomplete_terms_and_conditionsinvalid_url_website_incomplete_under_constructioninvalid_url_website_other
In the Accounts API, if no
settings.payments.statement_descriptoris supplied, the statement descriptor is automatically set to the first supplied parameter of (in priority order):business_profile.namebusiness_profile.urlcompany.nameorindividual.first_name+individual.last_name(dependent on thebusiness_type)
The statement descriptor is only set automatically when one of the above fields is provided as a parameter, so existing accounts will not be impacted unless a dependent field is updated. Similarly,
settings.card_payments.statement_descriptor_prefixwill be defaulted to a shortened version of thesettings.payments.statement_descriptor. This will take place whenever the statement descriptor is updated (either explicitly, or when defaulted).
2023-08-16
- Major
PaymentIntents and SetupIntents now have
automatic_payment_methodsenabled by default, which allows you to configure payment method settings from the Dashboard—no code required. The previous default was to accept only card payments when bothpayment_method_typesandautomatic_payment_methodswere not specified. For more information, view the upgrade guide.- When confirming a PaymentIntent, you will be required to provide a
return_urlunlessoff_session=true. - When confirming a PaymentIntent, you cannot use
error_on_requires_action. Usepayment_method_typeswitherror_on_requires_actionif you wish to fail payment attempts when PaymentIntents transition intorequires_action. - When confirming a SetupIntent, you will be required to provide a
return_url. - You can bypass the
return_urlrequirement usingautomatic_payment_methods[allow_redirects]=never, this will automatically filter payment methods that require redirect even if they are enabled in the Dashboard.
- When confirming a PaymentIntent, you will be required to provide a
No-cost orders are now enabled for one-time payments in Checkout Sessions. The value of
payment_method_collectionhas changed fromalwaystoif_requiredaccordingly.When being viewed by a platform, PaymentMethod fingerprints of types
us_bank_account,acss_debit,sepa_debit,bacs_debit, andau_becs_debitare rendered in platform scope, not the owning merchant (connected account) scope. This works similarly to the 2018-01-23 change for cards and bank accounts.Added more specific error codes to the PaymentIntent API for when a Klarna payment fails:
payment_method_customer_declinepayment_method_not_availablepayment_method_provider_declinepayment_intent_payment_attempt_expired
In the Accounts API,
verification_missing_directors,verification_directors_mismatch,verification_document_directors_mismatchandverification_extraneous_directorshas been added as a new error code in therequirements.errorsarray. See Account requirements errors for more information.
2022-11-15
Charge no longer auto-expands refunds by default. You can expand the list but for performance reasons we recommended against doing so unless needed.
The
chargesproperty on PaymentIntent has been removed. You can use thelatest_chargeproperty instead.Added more specific error codes for the following bank redirect payment methods: Bancontact, EPS, Giropay, iDEAL, Przelewy24, and Sofort.
Added the following error codes to the PaymentIntent and PaymentMethod APIs:
payment_intent_payment_attempt_expiredpayment_method_customer_declinepayment_method_provider_timeoutpayment_method_not_availablepayment_method_provider_decline
Added the following error codes to the SetupIntent APIs:
setup_intent_setup_attempt_expiredpayment_method_customer_declinepayment_method_provider_timeoutpayment_method_not_availablepayment_method_provider_decline
In the Accounts API,
verification_legal_entity_structure_mismatchhas been added as a new error code in therequirements.errorsarray. See Account requirements errors for more information.
2022-08-01
The
pending_invoice_items_behaviorparameter on create Invoice no longer supports theinclude_and_requirevalue. When the parameter is omitted the default value ofpending_invoice_items_behavioris nowexclude.When creating a Checkout Session in payment mode, the default value of
customer_creationhas changed fromalwaystoif_required.A PaymentIntent is no longer created during Checkout Session creation in payment mode. Instead, a PaymentIntent will be created when the Session is confirmed.
Checkout Sessions no longer return the
setup_intentproperty in subscription mode.The following parameters have been removed from create Checkout Session:
line_items[amount]line_items[currency]line_items[name]line_items[description]line_items[images]
You can use the
priceandprice_dataparameters instead.The
subscription_data[coupon]parameter has been removed from create Checkout Session. You can use thediscountsparameter instead.The
shipping_ratesparameter has been removed from create Checkout Session. You can use theshipping_optionsparameter instead.On the Checkout Session resource, several shipping properties have changed.
shipping_ratehas been moved into the newshipping_costhash.shippinghas been renamed toshipping_details.
exemptednow appears in thethree_d_securehash for card Charges. It indicates that a 3D Secure exemption was granted.In the Accounts API,
invalid_tos_acceptancehas been added as a new error code in therequirements.errorsarray. See Account requirements errors for more information.When creating a
physicalIssuing card in testmode, its shipping status no longer automatically changes frompendingtodelivered. This functionality is now accessible via the following new endpoints:/v1/test_helpers/issuing/cards/:card/shipping/ship/v1/test_helpers/issuing/cards/:card/shipping/deliver/v1/test_helpers/issuing/cards/:card/shipping/return/v1/test_helpers/issuing/cards/:card/shipping/fail
design_rejectedis now a possible value for thecancellation_reasonfield on the issued card object, indicating that the card’s design was rejected by Stripe.The
default_currencyfield on the Customer API resource has been removed.
2020-08-27
We have removed
tax_percentfrom objects and requests in favor of tax rates.On subscription schedules,
phases.planshas been renamed tophases.items. This applies for the subscription schedule object as well as create and update requests.Deprecate the
payment_method.card_automatically_updatedwebhook in favor ofpayment_method.automatically_updated.Checkout Sessions no longer include the
display_itemsproperty. Use the includableline_itemsproperty instead.The
requirementshash on the Account and Capability objects, and theverification_fieldshash on the Country Spec object have newly formatted strings for requirements that are related to key persons associated with an account:- Fields that are required for persons with
representative,owner,director, andexecutiveroles will be prefixed withrepresentative,owners,directors, andexecutives, respectively. Person requirements will be previewed as follows:- When the representative’s phone number is required, it will appear as
representative.phoneinstead ofrelationship.representative. - When an owner’s full name is required, it will appear as
owners.first_nameandowners.last_nameinstead ofrelationship.owner. - When an executive’s ID number is required, it will appear as
executives.id_numberinstead ofrelationship.executive. - When a director’s date of birth is required, it will appear as
directors.dob.day,directors.dob.month, anddirectors.dob.yearinstead ofrelationship.director.
- When the representative’s phone number is required, it will appear as
- The boolean values that indicate the associated owners, executives, or directors have been provided now appear as
company.owners_provided,company.executives_provided, orcompany.directors_providedinstead ofrelationship.owner,relationship.executive, orrelationship.director, respectively.
- Fields that are required for persons with
In the Accounts/Persons/Capabilities API, several new error codes have been introduced in the
requirements.errorsarray. See Account requirements errors for more information. These error codes are:verification_document_issue_or_expiry_date_missingverification_document_not_signedverification_failed_tax_id_not_issuedverification_failed_tax_id_matchinvalid_address_po_boxes_disallowed
The
payment_method_details.card.three_d_securefields on the Charge object have been updated. Thesucceededandauthenticatedbooleans have been removed; please use theresultenum instead.The
subscriptionsproperty on Customers is no longer included by default. You can expand the list but for performance reasons we recommended against doing so unless needed.The
tiersproperty on Plan is no longer included by default. You can expand the list but for performance reasons we recommended against doing so unless needed.The
sourcesproperty on Customers is no longer included by default. You can expand the list but for performance reasons we recommended against doing so unless needed.The
tax_idsproperty on Customers is no longer included by default. You can expand the list but for performance reasons we recommended against doing so unless needed.The
prorateandsubscription_prorateparameters are deprecated in favor ofproration_behavior.
2020-03-02
- Major
You can now optionally number invoices sequentially across your account instead of sequentially for each customer. To use this feature, enable account level numbering in the Stripe Dashboard.
- To ensure invoices are numbered sequentially and without gaps, invoices that can be deleted (drafts) are only assigned numbers when finalized.
2019-12-03
- Major
The
idfield of all invoice line items have changed and are now prefixed withil_. The new id has consistent prefixes across all line items, is globally unique, and can be used for pagination. Old prefixes includedsub_,su_,item_,sli_, andii_and weren’t globally unique.- You can no longer use the prefix of the id to determine the source of the line item. Instead use the
typefield for this purpose. - For lines with
type=invoiceitem, use theinvoice_itemfield to reference or update the originating Invoice Item object. - The Invoice Line Item object on earlier API versions also have a
unique_idfield to be used for migrating internal references before upgrading to this version. - When setting a tax rate to individual line items, use the new
id. Users on earlier API versions can pass in either a line itemidorunique_id.
- You can no longer use the prefix of the id to determine the source of the line item. Instead use the
When creating a post-payment credit note on an invoice:
out_of_band_amountis required if the sum ofcredit_amountand (refundorrefund_amount) is less than the credit note total.- In previous API versions
out_of_band_amountis optional and, in the case that thecredit_amountand refund amounts are less than the credit note total, the difference will automatically be allocated to theout_of_band_amount.
Customer balances applied to all invoices are now debited or credited back to the customer when voided. Earlier, applied customer balances were not returned back to the customer and were consumed.
- To achieve this behavior in earlier API versions:
- Set
consume_applied_balancetofalsewhen voiding invoices in/v1/invoices/:id/void. - Set
invoice_customer_balance_settings[consume_applied_balance_on_void]tofalsein/v1/subscriptionscreate or update to force this behavior for Invoices voided by a Subscription. - Set
subscription_data[invoice_customer_balance_settings][consume_applied_balance_on_void]tofalsein/v1/checkout/sessionscreate to force this behavior for Invoices voided by Subscriptions created with Checkout.
- Set
- To achieve this behavior in earlier API versions:
Deprecated tax information for Customers have been removed.
- The deprecated
tax_infoandtax_info_verificationfields on theCustomerobject are now removed in favor oftax_ids. - The deprecated
tax_infoparameter on theCustomercreate and update methods are removed in favor oftax_id_data. - For more information, view the migration guide.
- The deprecated
2019-11-05
In the Accounts API, the
requested_capabilitiesproperty is now required at creation time for Custom accounts in all countries. See Account capabilities for more information.On subscription schedules,
invoice_settings,default_payment_method,billing_thresholdsandcollection_methodare now nested underdefault_settings.
2019-10-17
There are changes to subscription schedules.
- Rename
renewal_behaviortoend_behaviorwith valuescancelandrelease. - Remove
renewal_interval. - A side effect of this change is that if you wrote a
renewal_behaviorofnoneon an old API version,end_behaviorwill be converted tocancelwhen reading the value back. - In the event that you are upgrading your API and set
renewal_behaviorasrenew, with this API version enabled you will seeend_behaviorasrenewhowever you will not be able to updaterenewal_interval. Additionally you can not setend_behaviortorenew, so it is in a read-only state.
- Rename
The
startfield on a subscription resource has been removed and is replaced by astart_datefield which represents when the entire subscription started as opposed to when the current plan configuration started.The
due_dateproperty is always null on invoices withbilling=charge_automatically.The
billingattribute on invoices, subscriptions, and subscription schedules is renamed tocollection_method.The customer object’s
account_balancevalue has been renamed tobalance. A new customer balance transactions API is available:- Update the customer’s
balanceby incrementing or decrementing its current value by a specifiedamountand attachingmetadatato the change. - Retrieve history of changes to the customer’s
balance.
- Update the customer’s
2019-10-08
The
relationship[account_opener]field on a Person object has been renamed torelationship[representative].
2019-09-09
In the Accounts API, the
requested_capabilitiesproperty is now required at creation time for accounts in Australia, Austria, Belgium, Denmark, Finland, France, Germany, Ireland, Italy, Luxembourg, the Netherlands, New Zealand, Norway, Portugal, Spain, Sweden, Switzerland, and the United Kingdom. See Account capabilities for more information.Adds additional
details_codevalues to theverification[document]hash on a Person object.
2019-08-14
- Major
The
platform_paymentscapability has been renamed totransfers, to better indicate the Stripe primitives that this capability supports.- The
card_paymentscapability has been updated to no longer implytransfers. You’ll now need to additionally request thetransferscapability when creating an account.
- The
The
relationship[executive]field on a Person object will no longer be automatically set totruewhen a Person object withrelationship[account_opener]is created. Therequirementshash on an Account object may require that you explicitly indicate that theaccount_openeris also anexecutive. If this is the case, you will need to indicate it by settingrelationship[executive]=true.
2019-05-16
Bank pull payments no longer expose internal system refunds on failure.
System refunds can still be accessed via the list refunds endpoint.
2019-03-14
The
application_feeparameter on invoice API methods and theapplication_feefield on the invoice object have both been renamed toapplication_fee_amount.- Major
Creating a subscription succeeds even when the first payment fails. The subscription will be created in an incomplete status, where it will remain for up to 23 hours. During that time period, it can be moved into an active state by paying the first invoice. If no successful payment is made, the subscription will move into a final incomplete_expired state. Updates to a non-incomplete subscription that require a payment will also succeed regardless of the payment status. Prior to this version, all creations or updates would fail if the corresponding payment failed. For more details see our guide.
There are a few changes to the invoice object:
- A
status_transitionshash now contains the timestamps when an invoice was finalized, paid, marked uncollectible, or voided. - The
dateproperty has been renamed tocreated. - The
finalized_atproperty has been moved into thestatus_transitionshash.
- A
2019-02-19
- Major
Statement descriptor behaviors for card payments created via
/v1/chargeshave changed. See our statement descriptor guide for details.- Instead of using the platform’s statement descriptor, charges created with
on_behalf_ofordestinationwill now use the descriptor of the connected account. - The full statement descriptor for a card payment may no longer be provided at charge creation. Dynamic descriptors provided at charge time will now be prefixed by the descriptor prefix set in the dashboard or via the new
settings[card_payments][statement_descriptor_prefix]parameter in the Accounts API. - If an account has no
statement_descriptorset, the account’s business or legal name will be used as statement descriptor. - Statement descriptors may no longer contain
*,', and".
- Instead of using the platform’s statement descriptor, charges created with
legal_entity[business_id_number]has been renamedlegal_entity[business_registration_number].- Major
Many properties on the Account API object have been reworked. To see a mapping of the old argument names to the new ones, see Accounts API Argument Changes.
- The
legal_entityproperty on the Account API resource has been replaced withindividual,company, andbusiness_type. - The
verificationhash has been replaced with arequirementshash.- The
verification[fields_needed]array has been replaced with three arrays to better represent when info is required:requirements[eventually_due],requirements[currently_due], andrequirements[past_due]. verification[due_by]has been renamed torequirements[current_deadline].- The
disabled_reasonenum value offields_neededhas been renamed torequirements.past_due.
- The
- Properties on the Account API object that configure behavior within Stripe have been moved into the new
settingshash.- The
payout_schedule,payout_statement_descriptoranddebit_negative_balancesfields have been moved tosettings[payouts]and renamed toschedule,statement_descriptoranddebit_negative_balances. - The
statement_descriptorfield has been moved tosettings[payments][statement_descriptor]. - The
decline_charge_onfields have been moved tosettings[card_payments]and renamed todecline_on. - The
business_logo,business_logo_largeandbusiness_primary_colorfields have been moved tosettings[branding]and renamed toicon,logoandprimary_color. Theiconfield additionally requires the uploaded image file to be square. - The
display_nameandtimezonefields have been moved tosettings[dashboard].
- The
business_name,business_url,product_description,support_address,support_email,support_phoneandsupport_urlhave been moved to thebusiness_profilesubhash.- The
legal_entity[verification][document]property (now located atindividual[verification]and atverificationin the Person API object) has been changed to a hash.- The
frontandbackfields support uploading both sides of documents. - The
details_codefield has new error types:document_corrupt,document_failed_copy,document_failed_greyscale,document_failed_other,document_failed_test_mode,document_fraudulent,document_id_country_not_supported,document_id_type_not_supported,document_invalid,document_manipulated,document_missing_back,document_missing_front,document_not_readable,document_not_uploaded,document_photo_mismatch, anddocument_too_large.
- The
- The
keysproperty on Account creation has been removed. Platforms should now authenticate as their connected accounts with their own key via theStripe-Accountheader. - Starting with the 2019-02-19 API, the
requested_capabilitiesproperty is now required at creation time for accounts in the U.S. See Account capabilities for more information.
- The
2019-02-11
Some PaymentIntent statuses have been renamed
requires_sourceis nowrequires_payment_methodrequires_source_actionis nowrequires_action- All other statuses are unchanged
save_source_to_customerhas been renamed tosave_payment_method.allowed_source_typeshas been renamed topayment_method_types.The
next_source_actionproperty on PaymentIntent has been renamed tonext_action, and theauthorize_with_urlwithin has been renamed toredirect_to_url.
2018-11-08
The
closedproperty on the invoice object controls automatic collection.closedhas been deprecated in favor of the more specificauto_advancefield. Where you might have setclosed=trueon invoices in the past, setauto_advance=false.auto_advancenow also defaults to false for one-off invoices, allowing you to control how long their status stays adraft. A longer explanation of these series of changes is in the documentation.Instead of checking the
forgivenfield on an invoice, check for theuncollectiblestatus.- Instead of setting the
forgivenfield on an invoice, mark it as uncollectible.
- Instead of setting the
The
immutable_frozen_invoiceerror code was renamed toinvoice_already_finalizedThe following changes only affect users of PaymentIntents as part of the private beta before November 15, 2018. If you did not use PaymentIntents before then, these don’t affect you.
- The
next_source_actiondictionary on PaymentIntents previously contained a key calledvalue. This has been replaced with theauthorize_with_urlanduse_stripe_sdkkeys. - When creating PaymentIntents, the
attempt_confirmationparameter has been renamed toconfirm. - The PaymentIntent confirm endpoint no longer supports the
payment_intentparameter. To update a PaymentIntent’s source, passsourceorsource_dataas a top-level parameter. - The
return_urlparameter is only allowed when confirming a PaymentIntent. Passingreturn_urlwhen updating a PaymentIntent is no longer allowed. - When creating a PaymentIntent with
transfer_data[destination], theon_behalf_ofparameter must be provided and must match the account provided totransfer_data[destination]. This is because when you provide a destination, Stripe will settle charges in the country of the destination account. - The
next_source_actiondictionary on PaymentIntents no longer contains thesource_typeproperty. To view the source type when retrieving PaymentIntents, expand thesourceparameter.
- The
2018-10-31
The
descriptionfield on customer endpoints has a maximum character length limit of350now. Thenamefield on product endpoints has a maximum character length limit of250now. Thedescriptionfield on invoice line items has a maximum character length limit of500now.The
billing_reasonattribute of the invoice object now can take the value ofsubscription_create, indicating that it is the first invoice of a subscription. For older API versions,billing_reason=subscription_createis represented assubscription_update.
2018-09-24
FileUploadobjects have been renamed toFileobjects. Additionally, theurlattribute now contains an authenticated URL (i.e. you will need to use your secret API key to download the file’s contents.) You can create a file link to obtain a publicly-accessible URL for the file.
2018-09-06
When creating or updating a SKU, its attribute values no longer need to be unique. It is now possible to create multiple SKUs without attributes or with identical attribute values.
2018-08-23
You can no longer set
at_period_endin the subscriptionDELETEendpoints. TheDELETEendpoint is reserved for immediate canceling going forward. Usecancel_at_period_endon the subscription update endpoints instead.The customer object’s
business_vat_idwas changed from String to Hash calledtax_info, consisting oftax_idandtype, in both requests and responses.The
amountfield field in thetiersconfiguration forplanswas renamed tounit_amount.
2018-07-27
The subscription endpoints no longer support the
sourceparameter. If you want to change the default source for a customer, instead use the source creation API to add the new source and then the customer update API to set it as the default.When ending a trial on a subscription using
trial_end=nowthe updated subscription will now receive atrial_endtimestamp from the time of the request rather than being unset.The
percent_offfield of coupons was changed from Integer to Float, with a precision of two decimal places.When creating or updating a customer the
emailparameter must contain an email address of valid shape.
2018-05-21
Products no longer have SKU lists embedded.
- Major
The
idfield of invoice line items oftype=subscriptionno longer can be interpreted as a subscription ID, but instead is a unique invoice line item ID. It can be used for pagination. Coupon, SKU, customer, product and plan
ids may only contain alphanumeric and_-characters on creation.- Major
When creating or updating subscriptions, the default value of
trial_from_planis nowfalse, meaning that a subscription will not automatically inherit a plan’strial_period_days. If a subscription is already trialing, switching to a new plan without specifyingtrial_from_planwill maintain the trial. We recommend setting an explicit trial per subscription instead of setting trials on plans. When changing the plan on a subscription to a new plan with a trial (together with
trial_from_plan=true), the new plan’s full trial period will be added to the subscription, without subtracting already-used time from previous trials.
2018-02-28
Updating a subscription set to cancel on a future date no longer clears the cancellation status. In order to clear the cancellation status, specify
cancel_at_period_end=falsewhen updating a subscription.
2018-02-06
For a Source’s
card[three_d_secure]property, addsrecommendedas a possible value. Previously, the only valid values werenot supported,optional, andrequired.
2018-02-05
- Major
Each plan object is now linked to a product object with
type=service. The plan objectstatement_descriptorandnameattributes have been moved to product objects, and plan objects now have anicknameattribute. Creating a plan now requires passing aproductattribute toPOST /v1/plans. This may be either an existing product ID or a dictionary of product fields, so that you may continue to create plans without separately creating products. Products now have a required
type:goodfor products used with Orders SKUs, orservicefor products used with Subscriptions and Plans.- On API versions older than 2018-02-05,
typeis set togoodby default, andGET /v1/productsomits products withtype=servicefrom the list. (If you want to see products withtype=serviceon API versions older than 2018-02-05, you can specifytype=servicewhen listing products.)
- On API versions older than 2018-02-05,
- Major
Allows a new subscription’s first full invoice to be on a future date, by specifying
billing_cycle_anchor, with an optional proration up to that date.billing_cycle_anchoron its own is available retroactively to past versions, and starting in this version,billing_cycle_anchorcan be combined with a trial, enabling a free trial to be followed by a prorated period, followed by a fixed billing cycle. Prorations on free plans now create $0 invoices. In past versions, these did not create invoices.
2018-01-23
When being viewed by a platform, cards and bank accounts created on behalf of connected accounts will have a fingerprint that is universal across all connected accounts. For accounts that are not connect platforms, there will be no change.
2017-12-14
Updates invoice payment attempts to return a
card_errorwhen the charge is declined. This aligns/v1/invoices/{INVOICE_ID}/paywith/v1/charges.Updates invoice line items to always have a
descriptionset, including invoice line items generated from subscription items.
2017-08-15
Adds
not_requiredas a possibleredirect[status]value on theSourceobject. Previously, optional redirects were marked assucceeded.
2017-06-05
Adds
under_reviewas a possibleverification[disabled_reason]value on theAccountobject. Previously, an under review status used the valueother.
2017-05-25
Replaces the
managedBoolean property onAccountobjects withtype, whose possible values are:standard,express, andcustom. Atypevalue is required when creating accounts. Thestandardtype replacesmanaged: false, and thecustomtype replacesmanaged: true.Updates the
previous_attributesproperty onEventobjects to show entire sub-arrays when those arrays have changes. Previously, those sub-arrays only showed the specific fields that changed.Updates the
requestproperty on theEventobject to be a hash containing the request ID and the idempotency key. Previously,requestwas just the ID.Renames the
user_idproperty on Connect-related event objects toaccount.
2017-04-06
- Major
Splits the
Transferobject intoPayoutandTransfer. ThePayoutobject represents money moving from a Stripe account to an external account (bank or debit card). TheTransferobject now only represents money moving between Stripe accounts on a Connect platform. For more details, see https://stripe.com/docs/transfer-payout-split.
2017-02-14
Updates the
disputeproperty on theChargeobject to contain the ID of an associated dispute. Previously,disputecontained the entireDisputeobject. You can expand this property when retrieving charges to render the fullDisputeobject as before.Updates the
outcome[rule]property on theChargeobject to contain the ID of the rule that blocked the charge. Previously,outcome[rule]contained the entireRuleobject. You can expand this property when retrieving charges to render the fullRuleobject as before.
2017-01-27
Removes the
sourced_transfersproperty from theBalance Transactionobject.
2016-10-19
Returns the status code 403 when an API request is made with insufficient permission. Previously, the API returned a 401 status code.
2016-07-06
Updates the list all subscriptions call to also return canceled subscriptions. The endpoint now supports fetching only canceled subscriptions by specifying
status=canceled. You can now retrieve a single canceled subscription by providing its ID.
2016-06-15
Updates the
activeproperty on theProductobject so that settingactiveto false no longer marks the product’s SKUs as inactive.
2016-03-07
Removes the
currencies_supportedproperty from theAccountobject. You can find a list of supported currencies by retrieving aCountry Specobject for the country of the account.
2016-02-29
Adds postal code validation for legal entity addresses when creating and updating accounts.
2016-02-23
Updates the behavior of orders so that changing an order from
paidorfulfilledtocanceledorreturnedautomatically refunds the associated charge. Previously, attempting to change an order frompaidorfulfilledtocanceledorreturnedraised an error if the associated charge had not already been refunded.
2016-02-22
Returns an error on attempts to add more than 250 invoice items to an invoice.
2016-02-19
Renames the
nameproperty on theBank Accountobject toaccount_holder_name.
2016-02-03
Updates the returned
Accountobject to only show sub-properties oflegal_entitythat are applicable to the account’s country, or that were previously provided.
2015-10-16
Returns an error if a
tax_percentis provided without aplanduring a customer update or creation.
2015-10-12
- Major
Returns an error when invalid parameters are passed in the card or bank account hash during token, source, or external account creation. Changes the error code returned for missing required parameters in the card or bank account hash to 400. Previously, a 402 code was returned.
2015-10-01
Replaces the
bank_accountsproperty on theAccountobject withexternal_accounts. Replaces thebank_accountvalue in thefields_neededproperty withexternal_account.
2015-09-23
Updates the
chargeproperty on theInvoiceobject to always show the invoice’s latest charge, regardless of the charge’s source (e.g, a card or a bank account). Removes thepaymentproperty, which previously reflected a non-card charge.- Major
Updates the list all charges call to return all charges, including those made to bank accounts and other non-card sources. Previously, it only returned charges made to cards. Updates the deprecated
offsetparameter to only be supported when filtering by source type.
2015-09-08
Updates API rate limit errors to return a 429 HTTP status code instead of 400. They also no longer return a
rate_limiterror code.
2015-09-03
Returns an error if a request reuses an idempotency token with different parameters than the original request. Previously, errors were only returned for reusing the same idempotency token across different API endpoints.
2015-08-19
Updates the
Balance Transactionobject to provide the refund ID or dispute ID as thesourcevalue when the balance transaction is associated with a refund or dispute. Previously, the original charge ID was shown.
2015-08-07
Adds date validation to the
tos_acceptance[date]property on theAccountobject. Accepted values are timestamps after 2009 and before the current moment.
2015-07-28
The
balance.availableevent is now triggered when immediate transfers are processed.
2015-07-13
Replaces the
verification[contacted]Boolean property on theAccountobject with averification[disabled_reason]string that describes why the account is unable to make transfers or charges.
2015-07-07
Updates the
statusproperty on theTransferobject so that transfers not yet submitted to the bank are stillpendingand transfers submitted to the bank that have not yet arrived arein_transit. Previously, both states were described aspending.
2015-06-15
Updates the
payout_schedule[delay_days]property on theAccountobject to return an error if provided when theintervalis set tomanual. Manual payouts always use the minimumdelay_daysvalue.
2015-04-07
Updates the
period[end]property on proration invoice line items to reflect the subscription’scurrent_period_endproperty when the update and proration was made. A proration invoice line item’speriod[start]andperiod[end]properties now represent the prorated adjustment interval. Previously,period[end]marked the time at which the proration was made, and was the same asperiod[start].Updates the
Invoiceobject to change the order of thelineslist: first invoice items in reverse chronological order, followed by the subscription, if applicable.
2015-03-24
Updates coupons so they no longer apply to negative invoice items by default. Previously, coupons applied to all non-proration invoice items. To allow a coupon to apply to a negative invoice item, pass
discountable=truewhen creating or updating the invoice item.
2015-02-18
Updates the
statusproperty on theChargeobject to have a value ofsucceededfor successful charges. Previously, thestatusproperty would bepaidfor successful charges.- Major
Replaces the
cardproperty on theChargeobject withsource. Provide this parameter with aCardtoken, as before, or with aSourcetoken that has anobjectvalue ofcard. Older API versions return both thecardandsourceproperties onCharge. - Major
Replaces the
cardsanddefault_cardproperties on theCustomerobject withsourcesanddefault_source. Both properties can representCardobjects, as before, andSourceobjects with anobjectvalue ofcard. Older API versions return both the new and old properties onCustomer. Replaces thecustomer.card.*andcustomer.bank_account.*events withcustomer.source.*.
2015-02-16
Renames the
transfer.canceledevent totransfer.reversed.
2015-02-10
Adds the value
warning_closedto thestatusproperty on theDisputeobject.Updates test mode transfers to require sufficient funds in your available test mode balance (for consistency with live mode transfers). Add funds directly to your available test mode balance—bypassing the pending balance—by creating a charge using the special test card number 4000 0000 0000 0077.
2015-01-26
Updates the presentation of nested hashes in the
previous_attributesproperty of events to only show the difference. For example, a change from{address: {line1: "Foo", line2: "Bar"}}to{address: {line1: "Foo", line2: "Baz"}}is represented as{previous_attributes: {address: {line2: "Baz"}}}. Previously, it was represented as{previous_attributes: {address: {line1: "Foo", line2: "Baz"}}}.Updates the
canceled_atproperty on theSubscriptionobject to always be the timestamp from the API call or invoice payment failure that canceled the subscription. Previously,canceled_atreflected “at period end” subscription cancellations, too. Theended_atproperty still reflects the time that the subscription actually stopped.
2015-01-11
Removes the
mimetypeproperty from theFile Uploadobject. Returns simplified file types in thetypeproperty and uses simpler naming conventions than mimetypes (e.g.,typecontains pdf instead of application/pdf).
2014-12-22
Updates the
Cardobject so a value ofuncheckedfor theaddress_line1_check,address_zip_check, orcvc_checkproperties means the property has not been checked. Previously, it meant the issuing bank does not support the particular check. That state now shows asunavailable. Unchecked properties are checked when a card is charged or added to aCustomerobject.Removes the
customerproperty from theCardobject that appears on theTokenobject.
2014-12-17
Replaces the
statement_descriptionproperty on theCharge,Invoice,Plan, andTransferobjects withstatement_descriptor. To determine what appears on a customer’s transaction,statement_descriptionis appended to your Stripe account’s statement descriptor whilestatement_descriptorsets the full statement value. If not on this API version or newer, providing astatement_descriptorstill triggers thestatement_descriptionbehavior. Regardless of API version, thestatement_descriptionbehavior does not apply with PaymentIntents.Updates the Accounts API to require API version 2014-12-17 or newer.
2014-12-08
Updates the
Disputeobject so evidence can be provided as a hash of typed fields rather than a single block of text. Replaces theevidence_due_byproperty with theevidence_detailshash, which includesdue_byandsubmission_count(for the number of times a dispute has been submitted).
2014-11-20
Updates disputes that are won to return the status
woneven if the charge was refunded. Previously, a dispute won that had a refunded charge would transition tocharge_refunded.Updates the
metadataproperty of theInvoice Itemobject with a type ofsubscriptionto show the subscription’s metadata. Previously, it showed the plan’s metadata.
2014-11-05
Renames the
charge_enabledandtransfer_enabledproperties on theAccountobject tocharges_enabledandtransfers_enabled.
2014-10-07
Prevents publishable keys from retrieving
Tokenobjects. When a card or bank account token is created with a publishable key, thefingerprintproperty is not included in the response.
2014-09-08
Replaces the
disabled,validated, andverifiedproperties on theBank Accountobject with astatusenum property.
2014-08-20
Adds three values to the
statusproperty on theDisputeobject:warning_needs_response,warning_under_review, andcharge_refunded. Replaces thebalance_transactionproperty of theDisputeobject withbalance_transactions(this provides greater detail around funds withdrawn and reinstated as a result of disputes).
2014-08-04
Removes the
other_transfers,summary, andtransactionsproperties from automatic transfer responses in favor of the balance history endpoint (/v1/balance/history).
2014-07-26
Changes the
refundsproperty on theApplication Feeobject from an array to a sublist object, which contains thedata,has_more, andurlproperties. This makes application fee refunds consistent with charge refunds.
2014-07-22
Updates proration line items on invoices to include the associated subscription’s plan and quantity.
2014-06-17
Changes the
refundsproperty on theChargeobject from an array to a sublist object, which contains thedata,has_more, andurlproperties.
2014-06-13
Renames the
typeproperty on theCardobject tobrand.
2014-05-19
Replaces the
accountproperty on theTransferobject withbank_account. Thebank_accountproperty is only included when the transfer is made to a bank account.
2014-03-28
- Major
Removes the
countproperty from list responses.
2014-03-13
Renames the
statement_descriptorproperty on theTransferobject tostatement_description.
2014-01-31
- Major
Replaces the
subscriptionproperty on theCustomerobject with thesubscriptionsproperty, as customers can have multiple subscriptions. Ignores trial dates on canceled subscriptions when automatically computing trial end dates for new subscriptions.
2013-12-03
Replaces the
useranduser_emailproperties on theApplication Feeobject with an expandableaccountproperty.Updates the refunding of application fees to be proportional to the amount of the charge refunded (when setting
refund_application_fee=true). Previously, the entire application fee was refunded even when only part of the charge was.
2013-10-29
- Major
Changes coupon behavior so that applying an amount-off coupon to an invoice does not increase the
Customeraccount balance if the discount is greater than the invoice amount. Coupons are ignored—and not counted as redeemed—when applied to zero-cost invoices. This change does not apply to coupons created on earlier API version.
2013-08-13
Removes the
feeandfee_detailsproperties from theChargeandTransferobjects. Fee information is in the corresponding balance transaction.
2013-08-12
Allows the
descriptionproperty onCustomer,Charge,InvoiceItem, andRecipientobjects, and theemailproperty onCustomerandRecipientobjects, to be set to null by providing empty string values in POST requests.
2013-07-05
- Major
Replaces the
active_cardproperty on theCustomerobject with acardssublist and adefault_cardID property.
2013-02-13
Updates the
Chargeobject so disputed charges include anotherstripe_feeobject in thefee_detailsarray, representing the dispute fees. Includes the dispute fees in the fee total on theChargeobject.
2013-02-11
- Major
Updates the pay invoice call to return an error when the charge is not successful. Previously, the API would return a 200 status and set the invoice’s
paidproperty to false.
2012-11-07
Replaces the
disputedproperty on theChargeobject withdispute.
2012-10-26
Updates the
Invoiceobject format. Thelinesproperty is now a sublist, a paginated list of all items that contribute to the invoice.
2012-09-24
Removes the extraneous
idproperty from theDiscountobject.
2012-07-09
Removes the
uncapturedproperty from theCustomerobject.
2012-06-28
- (Changes introduced in this version have since been removed.)
2012-06-18
Removes the
amountandcurrencyproperties from theTokenobject.
2012-03-25
Removes the
next_recurring_chargeproperty from theCustomerobject. Use the upcoming invoice call instead.
2012-02-23
Shows all response fields, even those with null values. Previously, the API hid fields with null values.
2011-11-17
- (Changes introduced in this version have since been removed.)
2011-09-15
Updates the card validation behavior when creating tokens.
2011-08-01
Updates the list format. New list objects have a
dataproperty that represents an array of objects (by default, 10) and acountproperty that represents the total count.
2011-06-28
Removes the
identifierproperty (duplicate ofid) from thePlanobject.
2011-06-21
Raises exceptions on unrecognized parameters passed to the API instead of silently allowing and ignoring them.