Your API version controls the API and webhook behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). Your version gets set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.

If you make requests on behalf of other users using Connect, we’ll use your application’s API version, making it easy for you to write code that works for all your users no matter what API versions they’re individually running.

Backwards-compatible changes

Stripe considers the following changes to be backwards-compatible:

• Adding new API resources.
• Adding new optional request parameters to existing API methods.
• Adding new properties to existing API responses.
• Changing the order of properties in existing API responses.
• Changing the length or format of object IDs or other opaque strings.
  This includes adding or removing fixed prefixes (such as ch_ on charge IDs).
  You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
• Adding new event types.
  Your webhook listener should gracefully handle unfamiliar event types.

Upgrading your API version

If you’re running an older version, you’ll want to upgrade to take advantage of the latest and greatest API, whether that means new functionality or streamlining the responses so the API is faster for you. To see what version you’re running and upgrade to the latest, visit your Dashboard.

Upgrading your API version will affect:

• 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 sent to your webhook endpoints (both Account and Connect ones.)

Testing a newer version for API calls can be made by setting the Stripe-Version header (in test or live mode). Read about Stripe’s support for versioning.

For webhooks, you can override the version of a single test webhook endpoint in your Dashboard. In order to safely upgrade your webhooks, Stripe recommends:

1. Check the API changelog to see which objects will be structured differently.
2. Update your webhook code to handle both the old and the new version of each objects.
3. Change the version of a test webhook endpoint to the version you want to test.
4. Trigger the event in test mode and validate that your code works for the new structure.

Once you are confident your code can handle the latest version, click the Upgrade version button in your Dashboard. This switches the version used by API calls with no Stripe-Version header as well as the version used to render objects sent to your webhooks.

Starting your upgrade will also switch the version of all your test webhook endpoints to the latest.

Rolling back your API version

For 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in your Dashboard.

After you’ve rolled back, webhooks that were sent with the new object structure and failed will be retried with the old structure.

Stay informed

We send information on new additions and changes to Stripe’s API and language libraries to the API announce mailing list. Be sure to subscribe to stay informed.

API changelog

The changelog is a list of backwards-incompatible updates in the API. As described above, new additions and forwards-compatible changes don’t need a new API version and will not appear in this list.

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_end=now the updated subscription will now receive a trial_end timestamp from the time of the request rather than being unset.
• The percent_off 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.

2018-05-21

• Products no longer have SKU lists embedded.
• MajorThe 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.
• MajorWhen creating or updating subscriptions, the default value of trial_from_plan is now false, meaning that a subscription will not automatically inherit a plan’s trial_period_days. If a subscription is already trialing, switching to a new plan without specifying trial_from_plan 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_from_plan=true), the new plan’s full trial period will be added to the subscription, without subtracting already-used time from previous trials.

2018-02-28

• Updating a subscription set to cancel on a future date no longer clears the cancellation status. In order to clear the cancellation status, specify cancel_at_period_end=false when updating a subscription.

2018-02-06

• For a Source’s card[three_d_secure] property, adds recommended as a possible value. Previously, the only valid values were not supported, optional, and required.

2018-02-05

• MajorEach plan object is now linked to a product object with type=service. The plan object fields statement_descriptor and name attributes have been moved to product objects. 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. Previous API versions will create a good type product if this field is omitted.
• MajorAllows a new subscription’s first full invoice to be on a future date, by specifying billing_cycle_anchor, with an optional proration up to that date.billing_cycle_anchor on its own is available retroactively to past versions, and starting in this version, billing_cycle_anchor 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.

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_error when the charge is declined. This aligns /v1/invoices/{INVOICE_ID}/pay with /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_required as a possible redirect[status] value on the Source object. Previously, optional redirects were marked as succeeded.

2017-06-05

• Adds under_review as a possible verification[disabled_reason] value on the Account object. Previously, an under review status used the value other.

2017-05-25

• Replaces the managed Boolean property on Account objects with type, whose possible values are: standard, express, and custom. A managed value is required when creating accounts.
• Updates the previous_attributes 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_id property on Connect-related event objects to account.

2017-04-06

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

2017-02-14

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

2017-01-27

• Removes the sourced_transfers property from the 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 the Product object so that setting active to false no longer marks the product’s SKUs as inactive.

2016-03-07

• Removes the currencies_supported 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.

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

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 the Bank Account object to account_holder_name.

2016-02-03

• Updates the returned Account object to only show sub-properties of legal_entity that are applicable to the account’s country, or that were previously provided.

2015-10-16

• Returns an error if a tax_percent is provided without a plan during a customer update or creation.

2015-10-12

• MajorReturns 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_accounts property on the Account object with external_accounts. Replaces the bank_account value in the fields_needed property with external_account.

2015-09-23

• 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.
• MajorUpdates 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_limit error code.

2015-09-03

• Returns an error if a request reuses an idempotency token with different parameters than the original request. Previously, errors were only returned for reusing the same idempotency token across different API endpoints.

2015-08-19

• Updates the Balance 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.

2015-08-07

• Adds date validation to the tos_acceptance[date] property on the Account object. Accepted values are timestamps after 2009 and before the current moment.

2015-07-28

• The balance.available event is now triggered when immediate transfers are processed.

2015-07-13

• Replaces the verification[contacted] Boolean property on the Account object with a verification[disabled_reason] string that describes why the account is unable to make transfers or charges.

2015-07-07

• 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_transit. Previously, both states were described as pending.

2015-06-15

• Updates the payout_schedule[delay_days] 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_days value.

2015-04-07

• Updates the period[end] property on proration invoice line items to reflect the subscription’s current_period_end 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.

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 the Charge object to have a value of succeeded for successful charges. Previously, the status property would be paid for successful charges.
• MajorReplaces 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.
• MajorReplaces the cards and default_card properties on the Customer object with sources and default_source. 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.card.* and customer.bank_account.* events with customer.source.*.

2015-02-16

• Renames the transfer.canceled event to transfer.reversed.

2015-02-10

• Adds the value warning_closed 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.

2015-01-26

• Updates the presentation of nested hashes in the previous_attributes 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_attributes: {address: {line2: "Baz"}}}. Previously, it was represented as {previous_attributes: {address: {line1: "Foo", line2: "Baz"}}}.
• Updates the canceled_at property on the Subscription object to always be the timestamp from the API call or invoice payment failure that canceled the subscription. Previously, canceled_at reflected “at period end” subscription cancellations, too. The ended_at property still reflects the time that the subscription actually stopped.

2015-01-11

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

2014-12-22

• Updates the Card object so a value of unchecked for the address_line1_check, address_zip_check, or cvc_check 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.

2014-12-17

• Replaces the statement_description property on the Charge, Invoice, Plan, and Transfer objects with statement_descriptor. To determine what appears on a customer’s transaction, statement_description is appended to your Stripe account’s statement descriptor while statement_descriptor sets the full statement value. If not on this API version or newer, providing a statement_descriptor still triggers the statement_description behavior.
• 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 the evidence_due_by property with the evidence_details hash, which includes due_by and submission_count (for the number of times a dispute has been submitted).

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 to charge_refunded.
• 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.

2014-11-05

• Renames the charge_enabled and transfer_enabled properties on the Account object to charges_enabled and 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, the fingerprint property is not included in the response.

2014-09-08

• Replaces the disabled, validated, and verified properties on the Bank Account object with a status enum property.

2014-08-20

• Adds three values to the status property on the Dispute object: warning_needs_response, warning_under_review, and charge_refunded. Replaces the balance_transaction property of the Dispute object with balance_transactions (this provides greater detail around funds withdrawn and reinstated as a result of disputes).

2014-08-04

• Removes the other_transfers, summary, and transactions properties from automatic transfer responses in favor of the balance history endpoint (/v1/balance/history).

2014-07-26

• Changes the refunds property on the Application Fee object from an array to a sublist object, which contains the data, has_more, and 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 the Charge object from an array to a sublist object, which contains the data, has_more, and url properties.

2014-06-13

• Renames the type property on the Card object to brand.

2014-05-19

• Replaces the account property on the Transfer object with bank_account. The bank_account property is only included when the transfer is made to a bank account.

2014-03-28

• MajorRemoves the count property from list responses.

2014-03-13

• Renames the statement_descriptor property on the Transfer object to statement_description.

2014-01-31

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

2013-12-03

• Replaces the user and user_email 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_application_fee=true). Previously, the entire application fee was refunded even when only part of the charge was.

2013-10-29

• MajorChanges 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 and fee_details properties from the Charge and Transfer objects. Fee information is in the corresponding balance transaction.

2013-08-12

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

2013-07-05

• MajorReplaces the active_card property on the Customer object with a cards sublist and a default_card ID property.

2013-02-13

• Updates the Charge object so disputed charges include another stripe_fee object in the fee_details array, representing the dispute fees. Includes the dispute fees in the fee total on the Charge object.

2013-02-11

• MajorUpdates 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 the Charge object with dispute.

2012-10-26

• Updates the Invoice object format. The lines 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 the Discount object.

2012-07-09

• Removes the uncaptured property from the Customer object.

2012-06-28

• (Changes introduced in this version have since been removed.)

2012-06-18

• Removes the amount and currency properties from the Token object.

2012-03-25

• Removes the next_recurring_charge property from the 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 a count property that represents the total count.

2011-06-28

• Removes the identifier property (duplicate of id) from the Plan object.

2011-06-21

• Raises exceptions on unrecognized parameters passed to the API instead of silently allowing and ignoring them.