API Upgrades

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’s faster for you. To see what version you’re running and upgrade to the latest, visit your dashboard.

To test your code under another API version before committing to the change, make use of Stripe’s support for versioning.

API changelog

Note that this changelog only reflects backwards-incompatible updates, so make sure you’re subscribed to our API updates mailing list to keep up with new features that don’t happen to break existing code.

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 plan during customer update and creation.

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 accross 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 transfer intervals. Manual transfers will always have the minimum delay_days.

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

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

2015-01-11

• The mimetype field on file uploads has been removed. Simplified file types are now returned in the type field on file uploads and have simpler naming conventions than mimetypes (for example, the type field returns pdf instead of application/pdf).

2014-12-22

• The customer field is no longer included on the Card object that appears on the Token object.
• The unchecked value for cvc_check, address_line1_check, and address_zip_check now means that we have not yet checked these fields on the card. The fields will be checked once a card is charged or added to a customer and validated. What was previously unchecked, which is when your customer’s bank does not support a particular check, is now represented as unavailable.

2014-12-17

• The statement_description parameter on charges, invoices, transfers, and plans is now deprecated in favor of the statement_descriptor parameter, which allows you to specify the full descriptor that appears on your customer’s statement for the transaction. Specifying statement_descriptor without upgrading to this API version will still prepend your account’s statement descriptor to the transaction’s statement descriptor.

2014-12-08

• Evidence for disputes is now provided in a hash of typed fields rather than a single block of text. Additionally, the evidence_due_by field has been removed and replaced by an evidence_details hash which includes due_by and submission_count (for the number of times a dispute has been submitted).

2014-11-20

• For invoice line items with type subscription, the metadata field now shows the subscription’s metadata. It previously showed the plan’s metadata.
• Disputes that are won will now return the status won even if the charge has been refunded. Previously they would transition to the status charge_refunded.

2014-11-05

• Account resources now return transfers_enabled and charges_enabled rather than their singular counterparts (transfer_enabled/charge_enabled).

2014-10-07

• Publishable keys can no longer be used to retrieve token objects. When a card or bank account token is created with a publishable key, the fingerprint property is no longer included in the response.

2014-09-08

• Bank account objects now contain a status enum as opposed to disabled, verified, and validated booleans.

2014-08-20

• The status field on disputes may now contain three new values: warning_needs_response, warning_under_review, and charge_refunded. In order to provide greater detail around funds withdrawn and reinstated as a result of disputes, we’ve added a balance_transactions field to the resource, and are removing the corresponding balance_transaction field.

2014-08-04

• The transactions, summary, and other_transfers properties in automatic transfer responses have been removed in favor of the balance history endpoint (/v1/balance/history), which can be called with the transfer id (using the ?transfer= parameter) to filter transactions by transfer.

2014-07-26

• Change refunds property on application fee responses from an array to a sublist object, which contains the total_count, has_more, url and data parameters. This makes application fee refunds consistent with charge refunds.

2014-07-22

• Proration line items on invoices now include the associated subscription’s plan and quantity.

2014-06-17

• Change refunds property on charge responses from an array to a sublist object, which contains the total_count, has_more, url, and data parameters.

2014-06-13

• Rename type to brand on the card object.

2014-05-19

• Replace account property on transfer responses with the bank_account property, which contains the same information and does not appear when the transfer was not made to a bank account.

2014-03-28

• MajorRemove count property from list responses, replacing it with the optional property total_count. You can request that total_count be included in your responses by specifying include[]=total_count.

2014-03-13

• Remove statement_descriptor property on transfer object. The statement_descriptor property is replaced by the statement_description property.

2014-01-31

• MajorRemove subscription property on customer object. The subscription property is replaced by the subscriptions property, as customers can now have multiple subscriptions.
• Trial dates used on canceled subscriptions are now ignored when automatically computing trial end dates for new subscriptions.

2013-12-03

• Remove user and user_email on application fees in favor of an expandable account property.
• Passing in refund_application_fee=true when refunding a charge now refunds the application fee proportional to the amount of the charge refunded, not the entire amount.

2013-10-29

• When we apply a $Y coupon to a $X dollar invoice, we are no longer applying the remainder of the coupon to the account balance if Y > X. Applications of coupons to $0 invoices will no longer count as a redemption of the coupon. This does not apply to coupons created before this version, though we’re happy to fix old coupons for you; please email support+coupon@stripe.com.

2013-08-13

• Remove fee and fee_details properties on charge and transfer objects. Instead, fee information is now stored on the corresponding balance transaction.

2013-08-12

• Empty string values in POST requests now set the property to null. The following objects now have properties that can be unset (passing an empty string for any other property is an error): description (Customer, Charge, InvoiceItem, Recipient), email (Customer, Recipient),

2013-07-05

• MajorCustomer objects now include a cards sublist and a default_card id in place of a fully expanded active_card. The default_card attribute can be expanded into a card object when retrieving the customer but is not expanded by default.

2013-02-13

• Charge objects now include another stripe_fee object in the fee_details array representing the fees for a dispute when the charge has a dispute. The fee total on charge objects also now includes the dispute fees in its calculation.

2013-02-11

• Return an error in invoice pay call when the charge is not successful in order to be more consistent with the rest of the API (e.g., charge creation calls). Previously, we would return a 200 status with the invoice’s paid attribute set to false.

2012-11-07

• Remove disputed property on charges (in favor of dispute property).

2012-10-26

• Updates the format of invoice objects. The ‘lines’ property has changed from a structure that contained all of the items in the invoice (broken up by section), to what we call a ‘sublist’ – which is just a normal paginated list of all the items that contributed to this invoice.

2012-09-24

• Remove extraneous ID property on discount objects

2012-07-09

• Remove uncaptured property on customer object

2012-06-28

• Remove avs_check and cvc_check properties on token object. You can find these properties on the card attached to a charge or customer object instead.

2012-06-18

• Remove amount and currency properties on token object.

2012-03-25

• Remove next_recurring_charge property on customer object. Use the upcoming invoice call instead.

2012-02-23

• Show all response property keys, even for null values. Previously, the API hid keys with null values.

2011-11-17

2011-09-15

• Update card validation behavior when creating tokens.

2011-08-01

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

• Remove identifier (duplicate of ID) property on plan object.

2011-06-21

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