API upgrades
Keep track of changes and upgrades to the Stripe API.
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. Each major release, such as Acacia, includes backwards-incompatible changes. Each monthly release adds new backwards-compatible changes and uses the same name as the last major release, indicating that it’s safe to upgrade without adopting any backwards-incompatible changes. Follow these steps to upgrade your API version.
If you make requests on behalf of other users using Connect, we’ll use your application’s API version to help 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_
column (thebin COLLATE
configuration 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-Version
header: 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 available upgrade in Workbench
See the API version used by recent requests on your account and the latest available upgrade from the Overview tab in Workbench.
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 SDKs.
Upgrade and test your webhooks
Read our guide on how to handle webhook versioning.
Perform the upgrade
When you’re confident that your code can handle the latest API version, perform the upgrade using Workbench:
- Open the Overview tab in Workbench.
- In the API versions section, click Upgrade available which will be visible if a newer API version is available.
- Review which API version will be assigned to your account, and click Upgrade.
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 Workbench.
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.
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.
2024-09-30.acacia
New values have been added to the Issuing Card
shipping.
enum:status submitted
The
allow_
parameter may now be passed viaredisplay collect_
onconfig collect_
and viapayment_ method process_
onconfig process_
.payment_ intent The
customer_
parameter has been removed and is replaced by theconsent_ collected allow_
parameter on the [Terminal Process Setup Intent]](/docs/api/terminal/readers/process_setup_intent) endpoint. Instead of passingredisplay customer_
, passconsent_ collected=true allow_
orredisplay=always allow_
. Instead of passingredisplay=limited customer_
, passconsent_ collected=false allow_
.redisplay=unspecified 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.errors verification_
supportability
The alert.filter field has been deprecated in favour of a filters field on the actual config. For example,
alert.
.usage_ threshold. filter
2024-06-20
New values have been added to the Issuing Authorization
request_
enum:history. reason card_
canceled card_
expired cardholder_
blocked insecure_
authorization_ method pin_
blocked
On the Issuing Authorization resource and related
test_
APIs,helper fuel.
has been renamed tovolume_ decimal fuel.
.quantity_ decimal On the Issuing Transaction resource and related
test_
APIs,helper purchase_
has been renamed todetails. fuel. volume_ decimal purchase_
.details. fuel. quantity_ decimal The following undocumented fuel fields have been removed from the Issuing Transaction resource in favor of the
_
equivalents:decimal purchase_
details. fuel. unit_ cost purchase_
details. fuel. volume
The following undocumented fleet fields have been removed from the Issuing Transaction resource in favor of their corresponding
_
equivalents:decimal purchase_
details. fleet. reported_ breakdown. fuel. gross_ amount purchase_
details. fleet. reported_ breakdown. non_ fuel. gross_ amount purchase_
details. fleet. reported_ breakdown. tax. local_ amount purchase_
details. fleet. reported_ breakdown. tax. national_ amount
New values have been added to the Issuing Transaction
purchase_
enum:details. fuel. unit imperial_
gallon kilogram
pound
charging_
minute kilowatt_
hour
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, usecardholder_ prompt_ data. alphanumeric_ id driver_
,id vehicle_
,number unspecified_
orid user_
instead.id In the Capabilities API,
paused.
andinactivity 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:transfer_ payments gb_
for UK Bank Transfers (GBP customer balance payments)bank_ transfer_ payments jp_
for JP Bank Transfers (JPY customer balance payments)bank_ transfer_ payments mx_
for MX Bank Transfers (MXN customer balance payments)bank_ transfer_ payments sepa_
for SEPA Bank Transfers (EUR customer balance payments)bank_ transfer_ payments us_
for US Bank Transfers (USD customer balance payments)bank_ transfer_ payments
2024-04-10
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.async Fields under
rendering_
for invoices are now migrated underoptions rendering
.Product ‘features’ has been renamed to
marketing_
.features
2023-10-16
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.errors invalid_
address_ highway_ contract_ box invalid_
address_ private_ mailbox invalid_
business_ profile_ name invalid_
business_ profile_ name_ denylisted invalid_
company_ name_ denylisted invalid_
dob_ age_ over_ maximum invalid_
dob_ age_ under_ minimum invalid_
product_ description_ length invalid_
product_ description_ url_ match invalid_
statement_ descriptor_ business_ mismatch invalid_
statement_ descriptor_ denylisted invalid_
statement_ descriptor_ length invalid_
statement_ descriptor_ prefix_ denylisted invalid_
statement_ descriptor_ prefix_ mismatch invalid_
tax_ id_ format invalid_
url_ denylisted invalid_
url_ format invalid_
url_ web_ presence_ detected invalid_
url_ website_ business_ information_ mismatch invalid_
url_ website_ empty invalid_
url_ website_ inaccessible invalid_
url_ website_ inaccessible_ geoblocked invalid_
url_ website_ inaccessible_ password_ protected invalid_
url_ website_ incomplete invalid_
url_ website_ incomplete_ cancellation_ policy invalid_
url_ website_ incomplete_ customer_ service_ details invalid_
url_ website_ incomplete_ legal_ restrictions invalid_
url_ website_ incomplete_ refund_ policy invalid_
url_ website_ incomplete_ return_ policy invalid_
url_ website_ incomplete_ terms_ and_ conditions invalid_
url_ website_ incomplete_ under_ construction invalid_
url_ website_ other
In the Accounts API, if no
settings.
is supplied, the statement descriptor is automatically set to the first supplied parameter of (in priority order):payments. statement_ descriptor business_
profile. name business_
profile. url company.
orname individual.
+first_ name individual.
(dependent on thelast_ name business_
)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.
will be defaulted to a shortened version of thecard_ payments. statement_ descriptor_ prefix settings.
. This will take place whenever the statement descriptor is updated (either explicitly, or when defaulted).payments. statement_ descriptor
2023-08-16
- Major
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 bothpayment_ methods payment_
andmethod_ types automatic_
were not specified. For more information, view the upgrade guide.payment_ methods - When confirming a PaymentIntent, you will be required to provide a
return_
unlessurl off_
.session=true - When confirming a PaymentIntent, you cannot use
error_
. Useon_ requires_ action payment_
withmethod_ types error_
if you wish to fail payment attempts when PaymentIntents transition intoon_ requires_ action requires_
.action - When confirming a SetupIntent, you will be required to provide a
return_
.url - You can bypass the
return_
requirement usingurl automatic_
, this will automatically filter payment methods that require redirect even if they are enabled in the Dashboard.payment_ methods[allow_ redirects]=never
- 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_
has changed frommethod_ collection always
toif_
accordingly.required When being viewed by a platform, PaymentMethod fingerprints of types
us_
,bank_ account acss_
,debit sepa_
,debit bacs_
, anddebit 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.becs_ debit Added more specific error codes to the PaymentIntent API for when a Klarna payment fails:
payment_
method_ customer_ decline payment_
method_ not_ available payment_
method_ provider_ decline payment_
intent_ payment_ attempt_ expired
In the Accounts API,
verification_
,missing_ directors verification_
,directors_ mismatch verification_
anddocument_ directors_ mismatch verification_
has been added as a new error code in theextraneous_ directors requirements.
array. See Account requirements errors for more information.errors
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
charges
property on PaymentIntent has been removed. You can use thelatest_
property instead.charge 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_ expired payment_
method_ customer_ decline payment_
method_ provider_ timeout payment_
method_ not_ available payment_
method_ provider_ decline
Added the following error codes to the SetupIntent APIs:
setup_
intent_ setup_ attempt_ expired payment_
method_ customer_ decline payment_
method_ provider_ timeout payment_
method_ not_ available payment_
method_ provider_ decline
In the Accounts API,
verification_
has been added as a new error code in thelegal_ entity_ structure_ mismatch requirements.
array. See Account requirements errors for more information.errors
2022-08-01
The
pending_
parameter on create Invoice no longer supports theinvoice_ items_ behavior include_
value. When the parameter is omitted the default value ofand_ require pending_
is nowinvoice_ items_ behavior exclude
.When creating a Checkout Session in payment mode, the default value of
customer_
has changed fromcreation always
toif_
.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_
property in subscription mode.intent 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
price
andprice_
parameters instead.data The
subscription_
parameter has been removed from create Checkout Session. You can use thedata[coupon] discounts
parameter instead.The
shipping_
parameter has been removed from create Checkout Session. You can use therates shipping_
parameter instead.options On the Checkout Session resource, several shipping properties have changed.
shipping_
has been moved into the newrate shipping_
hash.cost shipping
has been renamed toshipping_
.details
exempted
now appears in thethree_
hash for card Charges. It indicates that a 3D Secure exemption was granted.d_ secure In the Accounts API,
invalid_
has been added as a new error code in thetos_ acceptance requirements.
array. See Account requirements errors for more information.errors When creating a
physical
Issuing card in testmode, its shipping status no longer automatically changes frompending
todelivered
. 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_
is now a possible value for therejected cancellation_
field on the issued card object, indicating that the card’s design was rejected by Stripe.reason The
default_
field on the Customer API resource has been removed.currency
2020-08-27
We have removed
tax_
from objects and requests in favor of tax rates.percent On subscription schedules,
phases.
has been renamed toplans phases.
. This applies for the subscription schedule object as well as create and update requests.items Deprecate the
payment_
webhook in favor ofmethod. card_ automatically_ updated payment_
.method. automatically_ updated Checkout Sessions no longer include the
display_
property. Use the includableitems line_
property instead.items The
requirements
hash on the Account and Capability objects, and theverification_
hash on the Country Spec object have newly formatted strings for requirements that are related to key persons associated with an account:fields - Fields that are required for persons with
representative
,owner
,director
, andexecutive
roles 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.
instead ofphone relationship.
.representative - When an owner’s full name is required, it will appear as
owners.
andfirst_ name owners.
instead oflast_ name relationship.
.owner - When an executive’s ID number is required, it will appear as
executives.
instead ofid_ number relationship.
.executive - When a director’s date of birth is required, it will appear as
directors.
,dob. day directors.
, anddob. month directors.
instead ofdob. year relationship.
.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.
, orexecutives_ provided company.
instead ofdirectors_ provided relationship.
,owner relationship.
, orexecutive relationship.
, respectively.director
- Fields that are required for persons with
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:errors verification_
document_ issue_ or_ expiry_ date_ missing verification_
document_ not_ signed verification_
failed_ tax_ id_ not_ issued verification_
failed_ tax_ id_ match invalid_
address_ po_ boxes_ disallowed
The
payment_
fields on the Charge object have been updated. Themethod_ details. card. three_ d_ secure succeeded
andauthenticated
booleans have been removed; please use theresult
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.ids The
prorate
andsubscription_
parameters are deprecated in favor ofprorate proration_
.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
id
field 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
type
field for this purpose. - For lines with
type=invoiceitem
, use theinvoice_
field to reference or update the originating Invoice Item object.item - The Invoice Line Item object on earlier API versions also have a
unique_
field to be used for migrating internal references before upgrading to this version.id - When setting a tax rate to individual line items, use the new
id
. Users on earlier API versions can pass in either a line itemid
orunique_
.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_
is required if the sum ofof_ band_ amount credit_
and (amount refund
orrefund_
) is less than the credit note total.amount - In previous API versions
out_
is optional and, in the case that theof_ band_ amount credit_
and refund amounts are less than the credit note total, the difference will automatically be allocated to theamount out_
.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_
toapplied_ balance false
when voiding invoices in/v1/invoices/:id/void
. - Set
invoice_
tocustomer_ balance_ settings[consume_ applied_ balance_ on_ void] false
in/v1/subscriptions
create or update to force this behavior for Invoices voided by a Subscription. - Set
subscription_
todata[invoice_ customer_ balance_ settings][consume_ applied_ balance_ on_ void] false
in/v1/checkout/sessions
create 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_
andinfo tax_
fields on theinfo_ verification Customer
object are now removed in favor oftax_
.ids - The deprecated
tax_
parameter on theinfo Customer
create 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_
property is now required at creation time for Custom accounts in all countries. See Account capabilities for more information.capabilities On subscription schedules,
invoice_
,settings default_
,payment_ method billing_
andthresholds collection_
are now nested undermethod default_
.settings
2019-10-17
There are changes to subscription schedules.
- Rename
renewal_
tobehavior end_
with valuesbehavior cancel
andrelease
. - Remove
renewal_
.interval - A side effect of this change is that if you wrote a
renewal_
ofbehavior none
on an old API version,end_
will be converted tobehavior cancel
when reading the value back. - In the event that you are upgrading your API and set
renewal_
asbehavior renew
, with this API version enabled you will seeend_
asbehavior renew
however you will not be able to updaterenewal_
. Additionally you can not setinterval end_
tobehavior renew
, so it is in a read-only state.
- Rename
The
start
field on a subscription resource has been removed and is replaced by astart_
field which represents when the entire subscription started as opposed to when the current plan configuration started.date The
due_
property is always null on invoices withdate billing=charge_
.automatically The
billing
attribute on invoices, subscriptions, and subscription schedules is renamed tocollection_
.method The customer object’s
account_
value has been renamed tobalance balance
. A new customer balance transactions API is available:- Update the customer’s
balance
by incrementing or decrementing its current value by a specifiedamount
and attachingmetadata
to the change. - Retrieve history of changes to the customer’s
balance
.
- Update the customer’s
2019-10-08
The
relationship[account_
field on a Person object has been renamed toopener] relationship[representative]
.
2019-09-09
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.capabilities Adds additional
details_
values to thecode verification[document]
hash on a Person object.
2019-08-14
- Major
The
platform_
capability has been renamed topayments transfers
, to better indicate the Stripe primitives that this capability supports.- The
card_
capability has been updated to no longer implypayments transfers
. You’ll now need to additionally request thetransfers
capability when creating an account.
- The
The
relationship[executive]
field on a Person object will no longer be automatically set totrue
when a Person object withrelationship[account_
is created. Theopener] requirements
hash on an Account object may require that you explicitly indicate that theaccount_
is also anopener executive
. 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_
parameter on invoice API methods and thefee application_
field on the invoice object have both been renamed tofee application_
.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_
hash now contains the timestamps when an invoice was finalized, paid, marked uncollectible, or voided.transitions - The
date
property has been renamed tocreated
. - The
finalized_
property has been moved into theat status_
hash.transitions
- A
2019-02-19
- Major
Statement descriptor behaviors for card payments created via
/v1/charges
have changed. See our statement descriptor guide for details.- Instead of using the platform’s statement descriptor, charges created with
on_
orbehalf_ of destination
will 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_
parameter in the Accounts API.payments][statement_ descriptor_ prefix] - If an account has no
statement_
set, the account’s business or legal name will be used as statement descriptor.descriptor - Statement descriptors may no longer contain
*
,'
, and"
.
- Instead of using the platform’s statement descriptor, charges created with
legal_
has been renamedentity[business_ id_ number] legal_
.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_
property on the Account API resource has been replaced withentity individual
,company
, andbusiness_
.type - The
verification
hash has been replaced with arequirements
hash.- The
verification[fields_
array has been replaced with three arrays to better represent when info is required:needed] requirements[eventually_
,due] requirements[currently_
, anddue] requirements[past_
.due] verification[due_
has been renamed toby] requirements[current_
.deadline] - The
disabled_
enum value ofreason fields_
has been renamed toneeded requirements.
.past_ due
- The
- Properties on the Account API object that configure behavior within Stripe have been moved into the new
settings
hash.- The
payout_
,schedule payout_
andstatement_ descriptor debit_
fields have been moved tonegative_ balances settings[payouts]
and renamed toschedule
,statement_
anddescriptor debit_
.negative_ balances - The
statement_
field has been moved todescriptor settings[payments][statement_
.descriptor] - The
decline_
fields have been moved tocharge_ on settings[card_
and renamed topayments] decline_
.on - The
business_
,logo business_
andlogo_ large business_
fields have been moved toprimary_ color settings[branding]
and renamed toicon
,logo
andprimary_
. Thecolor icon
field additionally requires the uploaded image file to be square. - The
display_
andname timezone
fields have been moved tosettings[dashboard]
.
- The
business_
,name business_
,url product_
,description support_
,address support_
,email support_
andphone support_
have been moved to theurl business_
subhash.profile - The
legal_
property (now located atentity[verification][document] individual[verification]
and atverification
in the Person API object) has been changed to a hash.- The
front
andback
fields support uploading both sides of documents. - The
details_
field has new error types:code 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_
, andphoto_ mismatch document_
.too_ large
- The
- The
keys
property on Account creation has been removed. Platforms should now authenticate as their connected accounts with their own key via theStripe-Account
header. - Starting with the 2019-02-19 API, the
requested_
property is now required at creation time for accounts in the U.S. See Account capabilities for more information.capabilities
- The
2019-02-11
Some PaymentIntent statuses have been renamed
requires_
is nowsource requires_
payment_ method requires_
is nowsource_ action requires_
action - All other statuses are unchanged
save_
has been renamed tosource_ to_ customer save_
.payment_ method allowed_
has been renamed tosource_ types payment_
.method_ types The
next_
property on PaymentIntent has been renamed tosource_ action next_
, and theaction authorize_
within has been renamed towith_ url redirect_
.to_ url
2018-11-08
The
closed
property on the invoice object controls automatic collection.closed
has been deprecated in favor of the more specificauto_
field. Where you might have setadvance closed=true
on invoices in the past, setauto_
.advance=false auto_
now also defaults to false for one-off invoices, allowing you to control how long their status stays aadvance draft
. A longer explanation of these series of changes is in the documentation.Instead of checking the
forgiven
field on an invoice, check for theuncollectible
status.- Instead of setting the
forgiven
field on an invoice, mark it as uncollectible.
- Instead of setting the
The
immutable_
error code was renamed tofrozen_ invoice invoice_
already_ finalized 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.
- The
next_
dictionary on PaymentIntents previously contained a key calledsource_ action value
. This has been replaced with theauthorize_
andwith_ url use_
keys.stripe_ sdk - When creating PaymentIntents, the
attempt_
parameter has been renamed toconfirmation confirm
. - The PaymentIntent confirm endpoint no longer supports the
payment_
parameter. To update a PaymentIntent’s source, passintent source
orsource_
as a top-level parameter.data - The
return_
parameter is only allowed when confirming a PaymentIntent. Passingurl return_
when updating a PaymentIntent is no longer allowed.url - When creating a PaymentIntent with
transfer_
, thedata[destination] on_
parameter must be provided and must match the account provided tobehalf_ of transfer_
. This is because when you provide a destination, Stripe will settle charges in the country of the destination account.data[destination] - The
next_
dictionary on PaymentIntents no longer contains thesource_ action source_
property. To view the source type when retrieving PaymentIntents, expand thetype source
parameter.
- The
2018-10-31
The
description
field on customer endpoints has a maximum character length limit of350
now. Thename
field on product endpoints has a maximum character length limit of250
now. Thedescription
field on invoice line items has a maximum character length limit of500
now.The
billing_
attribute of the invoice object now can take the value ofreason subscription_
, indicating that it is the first invoice of a subscription. For older API versions,create billing_
is represented asreason=subscription_ create subscription_
.update
2018-09-24
FileUpload
objects have been renamed toFile
objects. Additionally, theurl
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.
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_
in the subscriptionperiod_ end DELETE
endpoints. TheDELETE
endpoint is reserved for immediate canceling going forward. Usecancel_
on the subscription update endpoints instead.at_ period_ end The customer object’s
business_
was changed from String to Hash calledvat_ id tax_
, consisting ofinfo tax_
andid type
, in both requests and responses.The
amount
field field in thetiers
configuration forplans
was renamed tounit_
.amount
2018-07-27
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 aend=now trial_
timestamp from the time of the request rather than being unset.end The
percent_
field of coupons was changed from Integer to Float, with a precision of two decimal places.off When creating or updating a customer the
email
parameter must contain an email address of valid shape.
2018-05-21
Products no longer have SKU lists embedded.
- Major
The
id
field of invoice line items oftype=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
id
s may only contain alphanumeric and_
characters on creation.- - Major
When creating or updating subscriptions, the default value of
trial_
is nowfrom_ plan false
, meaning that a subscription will not automatically inherit a plan’strial_
. If a subscription is already trialing, switching to a new plan without specifyingperiod_ days trial_
will maintain the trial. We recommend setting an explicit trial per subscription instead of setting trials on plans.from_ plan 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.from_ plan=true
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_
when updating a subscription.at_ period_ end=false
2018-02-06
For a Source’s
card[three_
property, addsd_ secure] recommended
as 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_
anddescriptor name
attributes have been moved to product objects, and plan objects now have anickname
attribute. Creating a plan now requires passing aproduct
attribute 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
:good
for products used with Orders SKUs, orservice
for products used with Subscriptions and Plans.- On API versions older than 2018-02-05,
type
is set togood
by default, andGET /v1/products
omits products withtype=service
from the list. (If you want to see products withtype=service
on API versions older than 2018-02-05, you can specifytype=service
when 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_
, with an optional proration up to that date.cycle_ anchor billing_
on its own is available retroactively to past versions, and starting in this version,cycle_ anchor billing_
can be combined with a trial, enabling a free trial to be followed by a prorated period, followed by a fixed billing cycle.cycle_ anchor 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_
when the charge is declined. This alignserror /v1/invoices/{INVOICE_
withID}/pay /v1/charges
.Updates invoice line items to always have a
description
set, including invoice line items generated from subscription items.
2017-08-15
Adds
not_
as a possiblerequired redirect[status]
value on theSource
object. Previously, optional redirects were marked assucceeded
.
2017-06-05
Adds
under_
as a possiblereview verification[disabled_
value on thereason] Account
object. Previously, an under review status used the valueother
.
2017-05-25
Replaces the
managed
Boolean property onAccount
objects withtype
, whose possible values are:standard
,express
, andcustom
. Atype
value is required when creating accounts. Thestandard
type replacesmanaged: false
, and thecustom
type replacesmanaged: true
.Updates the
previous_
property onattributes 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 theEvent
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 toid account
.
2017-04-06
- Major
Splits the
Transfer
object intoPayout
andTransfer
. ThePayout
object represents money moving from a Stripe account to an external account (bank or debit card). TheTransfer
object 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
dispute
property on theCharge
object to contain the ID of an associated dispute. Previously,dispute
contained the entireDispute
object. You can expand this property when retrieving charges to render the fullDispute
object as before.Updates the
outcome[rule]
property on theCharge
object to contain the ID of the rule that blocked the charge. Previously,outcome[rule]
contained the entireRule
object. You can expand this property when retrieving charges to render the fullRule
object as before.
2017-01-27
Removes the
sourced_
property from thetransfers Balance Transaction
object.
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
active
property on theProduct
object so that settingactive
to false no longer marks the product’s SKUs as inactive.
2016-03-07
Removes the
currencies_
property from thesupported Account
object. You can find a list of supported currencies by retrieving aCountry Spec
object 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
paid
orfulfilled
tocanceled
orreturned
automatically refunds the associated charge. Previously, attempting to change an order frompaid
orfulfilled
tocanceled
orreturned
raised 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
name
property on theBank Account
object toaccount_
.holder_ name
2016-02-03
Updates the returned
Account
object to only show sub-properties oflegal_
that are applicable to the account’s country, or that were previously provided.entity
2015-10-16
Returns an error if a
tax_
is provided without apercent plan
during 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_
property on theaccounts Account
object withexternal_
. Replaces theaccounts bank_
value in theaccount fields_
property withneeded external_
.account
2015-09-23
Updates the
charge
property on theInvoice
object to always show the invoice’s latest charge, regardless of the charge’s source (e.g, a card or a bank account). Removes thepayment
property, 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
offset
parameter 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_
error code.limit
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 Transaction
object to provide the refund ID or dispute ID as thesource
value 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_
property on theacceptance[date] Account
object. Accepted values are timestamps after 2009 and before the current moment.
2015-07-28
The
balance.
event is now triggered when immediate transfers are processed.available
2015-07-13
Replaces the
verification[contacted]
Boolean property on theAccount
object with averification[disabled_
string that describes why the account is unable to make transfers or charges.reason]
2015-07-07
Updates the
status
property on theTransfer
object so that transfers not yet submitted to the bank are stillpending
and transfers submitted to the bank that have not yet arrived arein_
. Previously, both states were described astransit pending
.
2015-06-15
Updates the
payout_
property on theschedule[delay_ days] Account
object to return an error if provided when theinterval
is set tomanual
. Manual payouts always use the minimumdelay_
value.days
2015-04-07
Updates the
period[end]
property on proration invoice line items to reflect the subscription’scurrent_
property when the update and proration was made. A proration invoice line item’speriod_ end period[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
Invoice
object to change the order of thelines
list: 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=true
when creating or updating the invoice item.
2015-02-18
Updates the
status
property on theCharge
object to have a value ofsucceeded
for successful charges. Previously, thestatus
property would bepaid
for successful charges.- Major
Replaces the
card
property on theCharge
object withsource
. Provide this parameter with aCard
token, as before, or with aSource
token that has anobject
value ofcard
. Older API versions return both thecard
andsource
properties onCharge
. - Major
Replaces the
cards
anddefault_
properties on thecard Customer
object withsources
anddefault_
. Both properties can representsource Card
objects, as before, andSource
objects with anobject
value ofcard
. Older API versions return both the new and old properties onCustomer
. Replaces thecustomer.
andcard. * customer.
events withbank_ account. * customer.
.source. *
2015-02-16
Renames the
transfer.
event tocanceled transfer.
.reversed
2015-02-10
Adds the value
warning_
to theclosed status
property on theDispute
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.
2015-01-26
Updates the presentation of nested hashes in the
previous_
property of events to only show the difference. For example, a change fromattributes {address: {line1: "Foo", line2: "Bar"}}
to{address: {line1: "Foo", line2: "Baz"}}
is represented as{previous_
. Previously, it was represented asattributes: {address: {line2: "Baz"}}} {previous_
.attributes: {address: {line1: "Foo", line2: "Baz"}}} Updates the
canceled_
property on theat 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. Theat ended_
property still reflects the time that the subscription actually stopped.at
2015-01-11
Removes the
mimetype
property from theFile Upload
object. Returns simplified file types in thetype
property and uses simpler naming conventions than mimetypes (e.g.,type
contains pdf instead of application/pdf).
2014-12-22
Updates the
Card
object so a value ofunchecked
for theaddress_
,line1_ check address_
, orzip_ check 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 ascheck unavailable
. Unchecked properties are checked when a card is charged or added to aCustomer
object.Removes the
customer
property from theCard
object that appears on theToken
object.
2014-12-17
Replaces the
statement_
property on thedescription Charge
,Invoice
,Plan
, andTransfer
objects withstatement_
. To determine what appears on a customer’s transaction,descriptor statement_
is appended to your Stripe account’s statement descriptor whiledescription statement_
sets the full statement value. If not on this API version or newer, providing adescriptor statement_
still triggers thedescriptor statement_
behavior. Regardless of API version, thedescription statement_
behavior does not apply with PaymentIntents.description Updates the Accounts API to require API version 2014-12-17 or newer.
2014-12-08
Updates the
Dispute
object so evidence can be provided as a hash of typed fields rather than a single block of text. Replaces theevidence_
property with thedue_ by evidence_
hash, which includesdetails due_
andby submission_
(for the number of times a dispute has been submitted).count
2014-11-20
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 tocharge_
.refunded Updates the
metadata
property of theInvoice Item
object with a type ofsubscription
to show the subscription’s metadata. Previously, it showed the plan’s metadata.
2014-11-05
Renames the
charge_
andenabled transfer_
properties on theenabled Account
object tocharges_
andenabled transfers_
.enabled
2014-10-07
Prevents publishable keys from retrieving
Token
objects. When a card or bank account token is created with a publishable key, thefingerprint
property is not included in the response.
2014-09-08
Replaces the
disabled
,validated
, andverified
properties on theBank Account
object with astatus
enum property.
2014-08-20
Adds three values to the
status
property on theDispute
object:warning_
,needs_ response warning_
, andunder_ review charge_
. Replaces therefunded balance_
property of thetransaction Dispute
object withbalance_
(this provides greater detail around funds withdrawn and reinstated as a result of disputes).transactions
2014-08-04
Removes the
other_
,transfers summary
, andtransactions
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.
2014-07-26
Changes the
refunds
property on theApplication Fee
object from an array to a sublist object, which contains thedata
,has_
, andmore url
properties. 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
refunds
property on theCharge
object from an array to a sublist object, which contains thedata
,has_
, andmore url
properties.
2014-06-13
Renames the
type
property on theCard
object tobrand
.
2014-05-19
Replaces the
account
property on theTransfer
object withbank_
. Theaccount bank_
property is only included when the transfer is made to a bank account.account
2014-03-28
- Major
Removes the
count
property from list responses.
2014-03-13
Renames the
statement_
property on thedescriptor Transfer
object tostatement_
.description
2014-01-31
- Major
Replaces the
subscription
property on theCustomer
object with thesubscriptions
property, 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
user
anduser_
properties on theemail Application Fee
object with an expandableaccount
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.application_ fee=true
2013-10-29
- Major
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.
2013-08-13
Removes the
fee
andfee_
properties from thedetails Charge
andTransfer
objects. Fee information is in the corresponding balance transaction.
2013-08-12
Allows the
description
property onCustomer
,Charge
,InvoiceItem
, andRecipient
objects, and theemail
property onCustomer
andRecipient
objects, to be set to null by providing empty string values in POST requests.
2013-07-05
- Major
Replaces the
active_
property on thecard Customer
object with acards
sublist and adefault_
ID property.card
2013-02-13
Updates the
Charge
object so disputed charges include anotherstripe_
object in thefee fee_
array, representing the dispute fees. Includes the dispute fees in the fee total on thedetails Charge
object.
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
paid
property to false.
2012-11-07
Replaces the
disputed
property on theCharge
object withdispute
.
2012-10-26
Updates the
Invoice
object format. Thelines
property is now a sublist, a paginated list of all items that contribute to the invoice.
2012-09-24
Removes the extraneous
id
property from theDiscount
object.
2012-07-09
Removes the
uncaptured
property from theCustomer
object.
2012-06-28
- (Changes introduced in this version have since been removed.)
2012-06-18
Removes the
amount
andcurrency
properties from theToken
object.
2012-03-25
Removes the
next_
property from therecurring_ charge Customer
object. 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
data
property that represents an array of objects (by default, 10) and acount
property that represents the total count.
2011-06-28
Removes the
identifier
property (duplicate ofid
) from thePlan
object.
2011-06-21
Raises exceptions on unrecognized parameters passed to the API instead of silently allowing and ignoring them.