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.

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.

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

  • Subscription metadata is no longer the same as the underlying 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

  • Display refunds on charges and application fees as a list.

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

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.