We’re making a small change to the Chargify API and we wanted you to know about it.  If you use the API to pull Transactions or create Credits, then you’ll want to read on to see what’s changing.  If you don’t do either of these things, you shouldn’t need to change anything.  Here are the details of the change and the new functionality that’s coming with it:

What’s Changing

We are changing the way Chargify “Credit” Transactions work behind the scenes.  Today, Credits deduct an amount from a Subscription’s balance, but are represented with a positive “amount”.  For example:

Old Subscription Balance:  $40
Applied Credit Amount:    $30
————————————————
New Subscription Balance:  $10

Since it would be nice to also adjust the balance up in some cases, we’re introducing Adjustments.  Adjustments with positive amounts make the balance go up, Adjustments with negative amounts make the balance go down (like Credits).

Old Subscription Balance:  $40
Applied Adjustment 1:    -$30
Applied Adjustment 2:    $ 5
————————————————
New Subscription Balance:  $15

Internally, we’re converting all existing Credits to Adjustments.

What this means for you

If you create Credits today via the API, then you’ll still be able to make the same API call you do already – you’ll still specify a positive amount to credit, which will cause the balance to go down.  However, the resource that is actually created will be an Adjustment with a negative amount.  This will be reflected back to you in the API response when you successfully create a Credit – the amount will be negative and the transaction_type will be ‘adjustment’.

You’ll also be able to create Adjustments—both positive and negative—directly from the API and forget about Credits if you want.

If you pull Transactions via the API,  you will no longer see transactions with transaction_type of ‘credit’.  If you display account transactions in your app or service, you may need to add support for the new Adjustments.

Implementation Date

These changes will go live between 1am and 7am EST on Saturday, December 18th.

With the introduction of Adjustments, you’ll have more control over the current balance of your subscriptions and be able to make arbitrary changes much more easily.

This change has made us think about introducing versioning to the API, but we’re holding off on that for now.  Since creating Credits still works just as it did, and we’re only extending functionality by adding Adjustments, we hope that no one will need to make any changes to their implementations.  If you have any concerns or comments, please let us know.