See the API version used by recent requests on your account and the latest available upgrade from the Overview tab in Workbench.
html stripe Upgrade and test your webhooks https://stripe.com/docs/upgrades#Upgrade and test your webhooksRead our guide on how to handle webhook versioning.
html stripe Perform the upgrade https://stripe.com/docs/upgrades#Perform the upgradeWhen you’re confident that your code can handle the latest API version, perform the upgrade using Workbench:
html stripe Roll back your API version https://stripe.com/docs/upgrades#Roll back your API versionFor 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in Workbench.
html stripe 1718834400 2024-06-20 https://stripe.com/docs/upgrades#2024-06-20New values have been added to the Issuing Authorization request_ enum:
card_card_cardholder_insecure_pin_On the Issuing Authorization resource and related test_ APIs, fuel. has been renamed to fuel..
On the Issuing Transaction resource and related test_ APIs, purchase_ has been renamed to purchase_.
The following undocumented fuel fields have been removed from the Issuing Transaction resource in favor of the _ equivalents:
purchase_purchase_The following undocumented fleet fields have been removed from the Issuing Transaction resource in favor of their corresponding _ equivalents:
purchase_purchase_purchase_purchase_New values have been added to the Issuing Transaction purchase_ enum:
imperial_kilogrampoundcharging_kilowatt_The fleet. property on the Issuing Authorization resource has been deprecated and will be removed in a future API version. Depending on the configuration of your card program, use driver_, vehicle_, unspecified_ or user_ instead.
In the Capabilities API, paused. and other have been added as new disabled reasons. See Capability disabled reasons for more information.
In the Capabilities API, bank_ capability type is being deprecated in favor of newer capability types per buyer’s location. The newer capability types are:
gb_ for UK Bank Transfers (GBP customer balance payments)jp_ for JP Bank Transfers (JPY customer balance payments)mx_ for MX Bank Transfers (MXN customer balance payments)sepa_ for SEPA Bank Transfers (EUR customer balance payments)us_ for US Bank Transfers (USD customer balance payments)PaymentIntents now has automatic_ as the default capture method when capture method is not specified during PaymentIntents creation. For more information about async capture, view the asynchronous capture guide.
Fields under rendering_ for invoices are now migrated under rendering.
Product ‘features’ has been renamed to marketing_.
In the Accounts API, the following error codes have been added as new error codes in the requirements. array. See Account requirements errors for more information.
invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_invalid_In the Accounts API, if no settings. is supplied, the statement descriptor is automatically set to the first supplied parameter of (in priority order):
business_business_company. or individual. + individual. (dependent on the business_)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. will be defaulted to a shortened version of the settings.. This will take place whenever the statement descriptor is updated (either explicitly, or when defaulted).
PaymentIntents and SetupIntents now have automatic_ enabled 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 both payment_ and automatic_ were not specified. For more information, view the upgrade guide.
return_ unless off_.error_. Use payment_ with error_ if you wish to fail payment attempts when PaymentIntents transition into requires_.return_.return_ requirement using automatic_, this will automatically filter payment methods that require redirect even if they are enabled in the Dashboard.No-cost orders are now enabled for one-time payments in Checkout Sessions. The value of payment_ has changed from always to if_ accordingly.
When being viewed by a platform, PaymentMethod fingerprints of types us_, acss_, sepa_, bacs_, and au_ are 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_payment_payment_payment_In the Accounts API, verification_, verification_, verification_ and verification_ has been added as a new error code in the requirements. array. See Account requirements errors for more information.
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 charges property on PaymentIntent has been removed. You can use the latest_ property 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_payment_payment_payment_payment_Added the following error codes to the SetupIntent APIs:
setup_payment_payment_payment_payment_In the Accounts API, verification_ has been added as a new error code in the requirements. array. See Account requirements errors for more information.
The pending_ parameter on create Invoice no longer supports the include_ value. When the parameter is omitted the default value of pending_ is now exclude.
When creating a Checkout Session in payment mode, the default value of customer_ has changed from always to if_.
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_ property in subscription mode.
The following parameters have been removed from create Checkout Session:
line_line_line_line_line_You can use the price and price_ parameters instead.
The subscription_ parameter has been removed from create Checkout Session. You can use the discounts parameter instead.
The shipping_ parameter has been removed from create Checkout Session. You can use the shipping_ parameter instead.
On the Checkout Session resource, several shipping properties have changed.
shipping_ has been moved into the new shipping_ hash.shipping has been renamed to shipping_.exempted now appears in the three_ hash for card Charges. It indicates that a 3D Secure exemption was granted.
In the Accounts API, invalid_ has been added as a new error code in the requirements. array. See Account requirements errors for more information.
When creating a physical Issuing card in testmode, its shipping status no longer automatically changes from pending to delivered. This functionality is now accessible via the following new endpoints:
/v1/test_/v1/test_/v1/test_/v1/test_design_ is now a possible value for the cancellation_ field on the issued card object, indicating that the card’s design was rejected by Stripe.
The default_ field on the Customer API resource has been removed.
We have removed tax_ from objects and requests in favor of tax rates.
On subscription schedules, phases. has been renamed to phases.. This applies for the subscription schedule object as well as create and update requests.
Deprecate the payment_ webhook in favor of payment_.
Checkout Sessions no longer include the display_ property. Use the includable line_ property instead.
The requirements hash on the Account and Capability objects, and the verification_ hash on the Country Spec object have newly formatted strings for requirements that are related to key persons associated with an account:
representative, owner, director, and executive roles will be prefixed with representative, owners, directors, and executives, respectively. Person requirements will be previewed as follows:representative. instead of relationship..owners. and owners. instead of relationship..executives. instead of relationship..directors., directors., and directors. instead of relationship..company., company., or company. instead of relationship., relationship., or relationship., respectively.In the Accounts/Persons/Capabilities API, several new error codes have been introduced in the requirements. array. See Account requirements errors for more information. These error codes are:
verification_verification_verification_verification_invalid_The payment_ fields on the Charge object have been updated. The succeeded and authenticated booleans have been removed; please use the result enum instead.
The subscriptions property 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 tiers property 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 sources property 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_ property 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 prorate and subscription_ parameters are deprecated in favor of proration_.
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.
The id field of all invoice line items have changed and are now prefixed with il_. The new id has consistent prefixes across all line items, is globally unique, and can be used for pagination. Old prefixes included sub_, su_, item_, sli_, and ii_ and weren’t globally unique.
type field for this purpose.type=invoiceitem, use the invoice_ field to reference or update the originating Invoice Item object.unique_ field to be used for migrating internal references before upgrading to this version.id. Users on earlier API versions can pass in either a line item id or unique_.When creating a post-payment credit note on an invoice:
out_ is required if the sum of credit_ and (refund or refund_) is less than the credit note total.out_ is optional and, in the case that the credit_ and refund amounts are less than the credit note total, the difference will automatically be allocated to the out_.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.
consume_ to false when voiding invoices in /v1/invoices/:id/void.invoice_ to false in /v1/subscriptions create or update to force this behavior for Invoices voided by a Subscription.subscription_ to false in /v1/checkout/sessions create to force this behavior for Invoices voided by Subscriptions created with Checkout.Deprecated tax information for Customers have been removed.
tax_ and tax_ fields on the Customer object are now removed in favor of tax_.tax_ parameter on the Customer create and update methods are removed in favor of tax_.In the Accounts API, the requested_ property is now required at creation time for Custom accounts in all countries. See Account capabilities for more information.
On subscription schedules, invoice_, default_, billing_ and collection_ are now nested under default_.
There are changes to subscription schedules.
renewal_ to end_ with values cancel and release.renewal_.renewal_ of none on an old API version, end_ will be converted to cancel when reading the value back.renewal_ as renew, with this API version enabled you will see end_ as renew however you will not be able to update renewal_. Additionally you can not set end_ to renew, so it is in a read-only state.The start field on a subscription resource has been removed and is replaced by a start_ field which represents when the entire subscription started as opposed to when the current plan configuration started.
The due_ property is always null on invoices with billing=charge_.
The billing attribute on invoices, subscriptions, and subscription schedules is renamed to collection_.
The customer object’s account_ value has been renamed to balance. A new customer balance transactions API is available:
balance by incrementing or decrementing its current value by a specified amount and attaching metadata to the change.balance.The relationship[account_ field on a Person object has been renamed to relationship[representative].
In the Accounts API, the requested_ property 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_ values to the verification[document] hash on a Person object.
The platform_ capability has been renamed to transfers, to better indicate the Stripe primitives that this capability supports.
card_ capability has been updated to no longer imply transfers. You’ll now need to additionally request the transfers capability when creating an account.The relationship[executive] field on a Person object will no longer be automatically set to true when a Person object with relationship[account_ is created. The requirements hash on an Account object may require that you explicitly indicate that the account_ is also an executive. If this is the case, you will need to indicate it by setting relationship[executive]=true.
Bank pull payments no longer expose internal system refunds on failure.
System refunds can still be accessed via the list refunds endpoint.
The application_ parameter on invoice API methods and the application_ field on the invoice object have both been renamed to application_.
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:
status_ hash now contains the timestamps when an invoice was finalized, paid, marked uncollectible, or voided.date property has been renamed to created.finalized_ property has been moved into the status_ hash.Statement descriptor behaviors for card payments created via /v1/charges have changed. See our statement descriptor guide for details.
on_ or destination will now use the descriptor of the connected account.settings[card_ parameter in the Accounts API.statement_ set, the account’s business or legal name will be used as statement descriptor.*, ', and ".legal_ has been renamed legal_.
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.
legal_ property on the Account API resource has been replaced with individual, company, and business_.verification hash has been replaced with a requirements hash.verification[fields_ array has been replaced with three arrays to better represent when info is required: requirements[eventually_, requirements[currently_, and requirements[past_.verification[due_ has been renamed to requirements[current_.disabled_ enum value of fields_ has been renamed to requirements..settings hash.payout_, payout_ and debit_ fields have been moved to settings[payouts] and renamed to schedule, statement_ and debit_.statement_ field has been moved to settings[payments][statement_.decline_ fields have been moved to settings[card_ and renamed to decline_.business_, business_ and business_ fields have been moved to settings[branding] and renamed to icon, logo and primary_. The icon field additionally requires the uploaded image file to be square.display_ and timezone fields have been moved to settings[dashboard].business_, business_, product_, support_, support_, support_ and support_ have been moved to the business_ subhash.legal_ property (now located at individual[verification] and at verification in the Person API object) has been changed to a hash.front and back fields support uploading both sides of documents.details_ field has new error types: document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, document_, and document_.keys property on Account creation has been removed. Platforms should now authenticate as their connected accounts with their own key via the Stripe-Account header.requested_ property is now required at creation time for accounts in the U.S. See Account capabilities for more information.Some PaymentIntent statuses have been renamed
requires_ is now requires_requires_ is now requires_save_ has been renamed to save_.
allowed_ has been renamed to payment_.
The next_ property on PaymentIntent has been renamed to next_, and the authorize_ within has been renamed to redirect_.
The closed property on the invoice object controls automatic collection. closed has been deprecated in favor of the more specific auto_ field. Where you might have set closed=true on invoices in the past, set auto_.
auto_ now also defaults to false for one-off invoices, allowing you to control how long their status stays a draft. A longer explanation of these series of changes is in the documentation.
Instead of checking the forgiven field on an invoice, check for the uncollectible status.
forgiven field on an invoice, mark it as uncollectible.The immutable_ error code was renamed to invoice_
The 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.
next_ dictionary on PaymentIntents previously contained a key called value. This has been replaced with the authorize_ and use_ keys.attempt_ parameter has been renamed to confirm.payment_ parameter. To update a PaymentIntent’s source, pass source or source_ as a top-level parameter.return_ parameter is only allowed when confirming a PaymentIntent. Passing return_ when updating a PaymentIntent is no longer allowed.transfer_, the on_ parameter must be provided and must match the account provided to transfer_. This is because when you provide a destination, Stripe will settle charges in the country of the destination account.next_ dictionary on PaymentIntents no longer contains the source_ property. To view the source type when retrieving PaymentIntents, expand the source parameter.The description field on customer endpoints has a maximum character length limit of 350 now. The name field on product endpoints has a maximum character length limit of 250 now. The description field on invoice line items has a maximum character length limit of 500 now.
The billing_ attribute of the invoice object now can take the value of subscription_, indicating that it is the first invoice of a subscription. For older API versions, billing_ is represented as subscription_.
FileUpload objects have been renamed to File objects. Additionally, the url attribute 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.
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.
You can no longer set at_ in the subscription DELETE endpoints. The DELETE endpoint is reserved for immediate canceling going forward. Use cancel_ on the subscription update endpoints instead.
The customer object’s business_ was changed from String to Hash called tax_, consisting of tax_ and type, in both requests and responses.
The amount field field in the tiers configuration for plans was renamed to unit_.
The subscription endpoints no longer support the source parameter. 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_ the updated subscription will now receive a trial_ timestamp from the time of the request rather than being unset.
The percent_ field of coupons was changed from Integer to Float, with a precision of two decimal places.
When creating or updating a customer the email parameter must contain an email address of valid shape.
Products no longer have SKU lists embedded.
The id field of invoice line items of type=subscription no 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.
When creating or updating subscriptions, the default value of trial_ is now false, meaning that a subscription will not automatically inherit a plan’s trial_. If a subscription is already trialing, switching to a new plan without specifying trial_ will 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_), the new plan’s full trial period will be added to the subscription, without subtracting already-used time from previous trials.
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_ when updating a subscription.
For a Source’s card[three_ property, adds recommended as a possible value. Previously, the only valid values were not supported, optional, and required.
Each plan object is now linked to a product object with type=service. The plan object statement_ and name attributes have been moved to product objects, and plan objects now have a nickname attribute. Creating a plan now requires passing a product attribute to POST /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: good for products used with Orders SKUs, or service for products used with Subscriptions and Plans.
type is set to good by default, and GET /v1/products omits products with type=service from the list. (If you want to see products with type=service on API versions older than 2018-02-05, you can specify type=service when listing products.)Allows a new subscription’s first full invoice to be on a future date, by specifying billing_, with an optional proration up to that date.billing_ on its own is available retroactively to past versions, and starting in this version, billing_ can 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.
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.
Updates invoice payment attempts to return a card_ when the charge is declined. This aligns /v1/invoices/{INVOICE_ with /v1/charges.
Updates invoice line items to always have a description set, including invoice line items generated from subscription items.
Adds not_ as a possible redirect[status] value on the Source object. Previously, optional redirects were marked as succeeded.
Adds under_ as a possible verification[disabled_ value on the Account object. Previously, an under review status used the value other.
Replaces the managed Boolean property on Account objects with type, whose possible values are: standard, express, and custom. A type value is required when creating accounts. The standard type replaces managed: false, and the custom type replaces managed: true.
Updates the previous_ property on Event objects to show entire sub-arrays when those arrays have changes. Previously, those sub-arrays only showed the specific fields that changed.
Updates the request property on the Event object to be a hash containing the request ID and the idempotency key. Previously, request was just the ID.
Renames the user_ property on Connect-related event objects to account.
Splits the Transfer object into Payout and Transfer. The Payout object represents money moving from a Stripe account to an external account (bank or debit card). The Transfer object now only represents money moving between Stripe accounts on a Connect platform. For more details, see https://stripe.com/docs/transfer-payout-split.
Updates the dispute property on the Charge object to contain the ID of an associated dispute. Previously, dispute contained the entire Dispute object. You can expand this property when retrieving charges to render the full Dispute object as before.
Updates the outcome[rule] property on the Charge object to contain the ID of the rule that blocked the charge. Previously, outcome[rule] contained the entire Rule object. You can expand this property when retrieving charges to render the full Rule object as before.
Removes the sourced_ property from the Balance Transaction object.
Returns the status code 403 when an API request is made with insufficient permission. Previously, the API returned a 401 status code.
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.
Updates the active property on the Product object so that setting active to false no longer marks the product’s SKUs as inactive.
Removes the currencies_ property from the Account object. You can find a list of supported currencies by retrieving a Country Spec object for the country of the account.
Adds postal code validation for legal entity addresses when creating and updating accounts.
Updates the behavior of orders so that changing an order from paid or fulfilled to canceled or returned automatically refunds the associated charge. Previously, attempting to change an order from paid or fulfilled to canceled or returned raised an error if the associated charge had not already been refunded.
Returns an error on attempts to add more than 250 invoice items to an invoice.
Renames the name property on the Bank Account object to account_.
Updates the returned Account object to only show sub-properties of legal_ that are applicable to the account’s country, or that were previously provided.
Returns an error if a tax_ is provided without a plan during a customer update or creation.
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.
Replaces the bank_ property on the Account object with external_. Replaces the bank_ value in the fields_ property with external_.
Updates the charge property on the Invoice object to always show the invoice’s latest charge, regardless of the charge’s source (e.g, a card or a bank account). Removes the payment property, which previously reflected a non-card charge.
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 offset parameter to only be supported when filtering by source type.
Updates API rate limit errors to return a 429 HTTP status code instead of 400. They also no longer return a rate_ error code.
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.
Updates the Balance Transaction object to provide the refund ID or dispute ID as the source value when the balance transaction is associated with a refund or dispute. Previously, the original charge ID was shown.
Adds date validation to the tos_ property on the Account object. Accepted values are timestamps after 2009 and before the current moment.
The balance. event is now triggered when immediate transfers are processed.
Replaces the verification[contacted] Boolean property on the Account object with a verification[disabled_ string that describes why the account is unable to make transfers or charges.
Updates the status property on the Transfer object so that transfers not yet submitted to the bank are still pending and transfers submitted to the bank that have not yet arrived are in_. Previously, both states were described as pending.
Updates the payout_ property on the Account object to return an error if provided when the interval is set to manual. Manual payouts always use the minimum delay_ value.
Updates the period[end] property on proration invoice line items to reflect the subscription’s current_ property when the update and proration was made. A proration invoice line item’s period[start] and period[end] properties now represent the prorated adjustment interval. Previously, period[end] marked the time at which the proration was made, and was the same as period[start].
Updates the Invoice object to change the order of the lines list: first invoice items in reverse chronological order, followed by the subscription, if applicable.
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=true when creating or updating the invoice item.
Updates the status property on the Charge object to have a value of succeeded for successful charges. Previously, the status property would be paid for successful charges.
Replaces the card property on the Charge object with source. Provide this parameter with a Card token, as before, or with a Source token that has an object value of card. Older API versions return both the card and source properties on Charge.
Replaces the cards and default_ properties on the Customer object with sources and default_. Both properties can represent Card objects, as before, and Source objects with an object value of card. Older API versions return both the new and old properties on Customer. Replaces the customer. and customer. events with customer..
Renames the transfer. event to transfer..
Adds the value warning_ to the status property on the Dispute object.
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.
Updates the presentation of nested hashes in the previous_ property 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_. Previously, it was represented as {previous_.
Updates the canceled_ property on the Subscription object to always be the timestamp from the API call or invoice payment failure that canceled the subscription. Previously, canceled_ reflected “at period end” subscription cancellations, too. The ended_ property still reflects the time that the subscription actually stopped.
Removes the mimetype property from the File Upload object. Returns simplified file types in the type property and uses simpler naming conventions than mimetypes (e.g., type contains pdf instead of application/pdf).
Updates the Card object so a value of unchecked for the address_, address_, or cvc_ properties means the property has not been checked. Previously, it meant the issuing bank does not support the particular check. That state now shows as unavailable. Unchecked properties are checked when a card is charged or added to a Customer object.
Removes the customer property from the Card object that appears on the Token object.
Replaces the statement_ property on the Charge, Invoice, Plan, and Transfer objects with statement_. To determine what appears on a customer’s transaction, statement_ is appended to your Stripe account’s statement descriptor while statement_ sets the full statement value. If not on this API version or newer, providing a statement_ still triggers the statement_ behavior. Regardless of API version, the statement_ behavior does not apply with PaymentIntents.
Updates the Accounts API to require API version 2014-12-17 or newer.
Updates the Dispute object so evidence can be provided as a hash of typed fields rather than a single block of text. Replaces the evidence_ property with the evidence_ hash, which includes due_ and submission_ (for the number of times a dispute has been submitted).
Updates disputes that are won to return the status won even if the charge was refunded. Previously, a dispute won that had a refunded charge would transition to charge_.
Updates the metadata property of the Invoice Item object with a type of subscription to show the subscription’s metadata. Previously, it showed the plan’s metadata.
Renames the charge_ and transfer_ properties on the Account object to charges_ and transfers_.
Prevents publishable keys from retrieving Token objects. When a card or bank account token is created with a publishable key, the fingerprint property is not included in the response.
Replaces the disabled, validated, and verified properties on the Bank Account object with a status enum property.
Adds three values to the status property on the Dispute object: warning_, warning_, and charge_. Replaces the balance_ property of the Dispute object with balance_ (this provides greater detail around funds withdrawn and reinstated as a result of disputes).
Removes the other_, summary, and transactions properties from automatic transfer responses in favor of the balance history endpoint (/v1/balance/history). Update: As of June 20, 2024, these properties are no longer available in any versions, including those prior to 2014-08-04.
Changes the refunds property on the Application Fee object from an array to a sublist object, which contains the data, has_, and url properties. This makes application fee refunds consistent with charge refunds.
Updates proration line items on invoices to include the associated subscription’s plan and quantity.
Changes the refunds property on the Charge object from an array to a sublist object, which contains the data, has_, and url properties.
Renames the type property on the Card object to brand.
Replaces the account property on the Transfer object with bank_. The bank_ property is only included when the transfer is made to a bank account.
Removes the count property from list responses.
Renames the statement_ property on the Transfer object to statement_.
Replaces the subscription property on the Customer object with the subscriptions property, as customers can have multiple subscriptions.
Ignores trial dates on canceled subscriptions when automatically computing trial end dates for new subscriptions.
Replaces the user and user_ properties on the Application Fee object with an expandable account property.
Updates the refunding of application fees to be proportional to the amount of the charge refunded (when setting refund_). Previously, the entire application fee was refunded even when only part of the charge was.
Changes coupon behavior so that applying an amount-off coupon to an invoice does not increase the Customer account 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.
Removes the fee and fee_ properties from the Charge and Transfer objects. Fee information is in the corresponding balance transaction.
Allows the description property on Customer, Charge, InvoiceItem, and Recipient objects, and the email property on Customer and Recipient objects, to be set to null by providing empty string values in POST requests.
Replaces the active_ property on the Customer object with a cards sublist and a default_ ID property.
Updates the Charge object so disputed charges include another stripe_ object in the fee_ array, representing the dispute fees. Includes the dispute fees in the fee total on the Charge object.
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 paid property to false.
Replaces the disputed property on the Charge object with dispute.
Updates the Invoice object format. The lines property is now a sublist, a paginated list of all items that contribute to the invoice.
Removes the extraneous id property from the Discount object.
Removes the uncaptured property from the Customer object.
Removes the amount and currency properties from the Token object.
Removes the next_ property from the Customer object. Use the upcoming invoice call instead.
Shows all response fields, even those with null values. Previously, the API hid fields with null values.
Updates the card validation behavior when creating tokens.
Updates the list format. New list objects have a data property that represents an array of objects (by default, 10) and a count property that represents the total count.
Removes the identifier property (duplicate of id) from the Plan object.
Raises exceptions on unrecognized parameters passed to the API instead of silently allowing and ignoring them.