API Upgrades (Archived)

Keep track of changes and upgrades to the Qordoba API.

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.

Backwards-compatible changes

Qordoba considers the following changes 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 event types.

Stay informed

We send information on new additions and changes to Qordoba's API and language libraries in the Qordoba Developer email list. Be sure to subscribe to stay informed.