API upgrades

What is my API version?

Your API version controls the Stripe 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 Stripe 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 Stripe 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 Stripe 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.

2014-03-28

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

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

  • Customer 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 currency and amount parameters on token creation. (No longer needed.)

  • Remove schedule property on customer object

  • Remove uncaptured property on customer object

  • Remove suspended property on customer object

  • Remove uncaptured parameter on charge creation.

  • Remove suspended parameter on customer creation.

  • Remove schedule parameter on customer creation.

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

  • Raise exceptions when you try to associate test mode objects with live customers and vice versa, making inadvertent mistakes less likely.

2011-09-27

  • Remove an old charge creation API call.

  • Remove an old customer update API call.

2011-09-16

  • Update discount format.

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.