What is my API version?

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.

What changes does Stripe consider 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 events types.

How can I upgrade my API?

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.

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.

2017-12-14

• If paying an invoice fails due to an error authorizing the customer’s card (i.e. the card was declined), the request now returns a card_error. This aligns /v1/invoices/{INVOICE_ID}/pay with /v1/charges.
• All invoice line items now have a non null description set, including those that are generated from a subscription item.

2017-08-15

• Adds not_required as a possible redirect.status value on a Source object. Previously, optional redirects were marked as succeeded.

2017-06-05

• A new value, under_review, has been added to the enum of verification.disabled_reason on the account resource. under_review was previously shown as other.

2017-05-25

• The managed property on account objects has been replaced by the type property, and is now required for account creation. Possible values are standard, express, or custom.
• Event objects (and webhooks) now show entire sub-arrays in previous_attributes when those arrays have changes. Previously those sub-arrays only contained the specific fields that were changed.
• Event objects (and webhooks) will now render a request subobject that contains a request ID and idempotency key instead of just a string request ID.
• Renames the user_id property on Connect-related event objects to account.

2017-04-06

• MajorPayouts were moved out of Transfers into their own resource. /v1/payouts now represents moving money from a Stripe account to a bank account or debit card, and /v1/transfers now represents Connect platforms moving money between Stripe accounts. For more details, see https://stripe.com/docs/transfer-payout-split.

2017-02-14

• Charge objects will now render the ID of their dispute instead of the full Dispute object. You may expand this property to render the full Dispute as before.
• Charges that have been blocked by Radar rules will now render the ID of the rule that blocked them under the outcome field instead of the full Rule object. You may expand this property to render the full Rule as before.

2017-01-27

• API responses to /v1/balance/history endpoints will no longer return a sourced_transfers property on balance transaction objects.

2016-10-19

• The API will now return status code 403 instead of 401 when you make a request that has insufficient permissions.

2016-07-06

• You can now view canceled subscriptions by specifying status=canceled or status=all when listing subscriptions. In addition, you can now retrieve a canceled subscription by its ID.

2016-06-15

• When you set the active flag on a product to false, its SKUs will no longer automatically be marked as inactive.

2016-03-07

• API responses to /v1/accounts endpoints no longer return a currencies_supported property on account objects. Currency information varies based on an account’s country, and this information is still available via the new /v1/country_specs API. For details on the Country Specs API, see https://stripe.com/docs/api#country_specs.

2016-02-29

• Add strict checks for postal codes on the account update and account creation endpoints. See https://stripe.com/docs/api#update_account-legal_entity-address-postal_code for more details.

2016-02-23

• When an order is changed from paid or fulfilled to canceled, returned, the charge on the order is now automatically refunded. Previously, an attempt to change an order to state canceled or returned would raise an error if the order’s charge had not already been refunded.

2016-02-22

• An error is now returned when trying to add over 250 invoice items to an invoice

2016-02-19

• The name prop on the BankAccount resource is now deprecated. All values that were returned under name will now be returned under account_holder_name.

2016-02-03

• The legal_entity hash within the Accounts endpoint now only contains properties that are applicable for the account’s country. legal_entity properties that have been filled in will not be hidden.

2015-10-16

• An error is now returned if a tax_percent is provided without a planduring customer update and create.

2015-10-12

• MajorAn error is now returned if invalid parameters are passed in the card or bank account parameters hash during token, customer source, or external account creation. In addition, the error code for missing required parameters in these bank account or card hashes is now 400 instead of 402.

2015-10-01

• bank_accounts is no longer a field in the Account object. Use external_accounts instead. Also, bank_account will be replaced by external_account in fields_needed.

2015-09-23

• An invoice’s latest charge, if any, now always appears as the charge attribute of the invoice. Previously, a non-card charge appeared as the payment attribute, which no longer exists.
• MajorThe Charges endpoint previously returned only card charges. Charges now returns all charges, such as card charges and bank account charges. See the endpoint’s documentation for information on filtering by charge source type. The deprecated offset parameter is now only supported when filtering by charge source type. To simultaneously paginate charges from all sources, see https://stripe.com/docs/api#pagination.

2015-09-08

• API rate limit errors now return a HTTP status code of 429 instead of 400. They also no longer return a rate_limit error code.

2015-09-03

• An error is now returned if a request reuses an idempotency token with different parameters from the original request sharing the token. (Previously, errors were returned only when idempotency tokens were reused across different API endpoints.)

2015-08-19

• Balance transactions corresponding to refunds and disputes now show the refund ID or dispute ID instead of the charge ID as the source.

2015-08-07

• The tos_acceptance[date] field for accounts now performs date validation.Dates are expected to be integers, measured in seconds, not in the future,and after 2009.

2015-07-28

• The balance.available webhook is now sent when immediate transfers are processed.

2015-07-13

• The contacted boolean under account verification is now replaced with a disabled_reason string, describing why a certain account is unable to make transfers and/or charges.

2015-07-07

• The pending transfer status is now broken into two states. Transfers not yet submitted to the bank are still pending whereas transfers submitted to the bank but not yet paid now have the status in_transit.

2015-06-15

• For managed accounts, delay_days is now only accepted for non-manual payout intervals. Manual payouts will always have the minimum delay_days.(Delay days was previously ignored for manual payout intervals - now it raises an error.)

2015-04-07

• The period[end] attribute on proration invoice line items is now equal to current_period_end on the subscription when the update / proration was done. This means that period[start] and period[end] on the proration now represent the interval for which the prorated adjustment was made. (Previously, period[end] was the time at which the proration was made, and was the same as period[start].)
• Invoice items added to an invoice are now added to the front of the lines list, instead of the end. The old behavior was inconsistent with the sorting order of lines. On new invoices, lines is now expressly sorted as follows: invoice items in reverse chronological order, followed by the subscription, if any.

2015-03-24

• Coupons no longer apply to negative invoice items by default, whereas previously, coupons applied to all non-proration invoice items. A discountable property is now exposed by invoice items, which controls whether a coupon applies to it. If you need to have coupons apply to negative invoice items, you should pass discountable=true when creating or updating the invoice item.

2015-02-18

• The status attribute on Charges now takes the value succeeded if the charge succeeded (previously it took the value paid in that situation).
• MajorThe card attribute is no longer returned on Charges. You should now use the source attribute instead. If you only have card charges then you can use source exactly as you used card. Otherwise, you should check the object attribute of the source to determine what type of payment source it is. If the source has object='card' then it is a card object, and is identical to the card subhash returned on Charges in older API versions. Older API versions return both the card attribute and the source attribute.
• MajorThe cards and default_card attributes are no longer returned on Customers. You should now use sources and default_source respectively. The customer.card.* and customer.bank_account.* webhooks are now named customer.source.*. If you only have cards attached to customers (as opposed to payment sources of other types) then you can use the new attributes exactly as you would the old ones. If you have payment sources of multiple types, then the sources list contains heterogeneous objects and you can check the object attribute of each source to determine its format. Older API versions return both the new and the old attributes.

2015-02-16

• The transfer.canceled notification has been renamed to transfer.reversed.

2015-02-10

• The status field on disputes may now contain a new value: warning_closed.
• Transfers in test mode now require sufficient funds in your available test mode balance. This brings the test environment behavior into line with the live environment. To adds funds directly to your available test mode balance (bypassing the pending balance), you can use the special test card number 4000 0000 0000 0077.

2015-01-26

• Nested hashes in the previous_attributes field of events are now recursively diffed. For example, a change from {address: {line1: "Foo", line2: "Bar"}} to {address: {line1: "Foo", line2: "Baz"}} now sends {previous_attributes: {address: {line2: "Baz"}}}, whereas it used to send {previous_attributes: {address: {line1: "Foo", line2: "Baz"}}}.
• The canceled_at field is no longer changed when a subscription is canceled at period end. Now canceled_at will always be the timestamp from the API call or invoice payment failure event that canceled the subscription. The ended_at parameter will still give 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.