— No Results

    API Upgrades

    Keep track of changes and upgrades to the Stripe API.

    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.

    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.

    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.

    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.
    • The user_id field of Connect-related event objects (and webhooks) has been renamed 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

    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

    • 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 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.
    • The customer field is no longer included on the Card object that appears on the Token object.

    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.
    • The minimum API version necessary to use the Accounts API is 2014-12-17.

    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

    • 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.
    • For invoice line items with type subscription, the metadata field now shows the subscription’s metadata. It previously showed the plan’s metadata.

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

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

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

    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

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

    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.