Knowledge Base: API User Guide

The Chargify API allows you to keep the customer purchase flow on your own site, while passing the billing information to us for processing. The API attempts to conform to the RESTful design principles. It accepts method calls via HTTP and returns responses as JSON or XML.

In addition to querying, creating, and modifying resources such as your Customers and Subscriptions, you can also use the Chargify API to "authenticate" your users. In this way, you can determine whether a particular user has access to a particular resource on your site. In other words, does User X have access to Plan Y?

The Chargify API also supports callbacks to your own site, so you may be notified of important changes. This allows you to cache subscription data on your site, only making new requests for subscription data from us when we have notified you of a change.

API Wrappers

The following wrappers are available for the API. If you have usage examples or code libraries in other languages, we will happily accept your input and can help you host the repositories.

.Net

http://chargify.codeplex.com: A .Net API wrapper by one of our active beta testers (Kori Francis, @Djbyter)

Java / Scala

http://github.com/IntroSpectrum/chargify-scala: A Scala API wrapper by one of our active beta testers.

PHP

http://github.com/lewsid/chargify_api_php: A PHP API wrapper by one of our active beta testers.

Python

http://github.com/getyouridx/pychargify: A Python API wrapper by one of our active beta testers.

Ruby/ActiveResource (Rails)

http://github.com/grasshopperlabs/chargify_api_ares: This is the "official" gem by the Chargify team. It uses ActiveResource, which is built in to Rails, and is a good option for easy integration.
http://github.com/pengwynn/chargify: This is a Chargify API wrapper that uses HTTParty, by one of our active beta testers. It has tests by using a Chargify "mock".

Resources Available

The following resources are available via the API

Customers	Customers in Chargify are the resources that have access to your Products via a Subscription. These will usually map to the Users in your application.	View Documentation
Subscriptions	Subscriptions in Chargify give access to a particular Product for a particular Customer. They are usually recurring in nature, and all of the complexities of renewal, dunning, and expiration management are handled by Chargify.	View Documentation
Products	Products are the things which you sell.	View Documentation

Response Codes

An HTTP Response Code is sent for every request to the API, and will be one of the following

200 OK	The request succeeded and a response was sent. Usually in response to a GET (read) request, but also for successful PUT (update) requests.
201 Created	The resource was successfully created. Sent in response to a POST (create) request with valid data.
401 Unauthorized	Returned when API authentication has failed.
403 Forbidden	Returned by valid endpoints in our application that have not been enabled for API use.
404 Not Found	The requested resource was not found.
422 Unprocessable Entity	Sent in response to a POST (create) or PUT (update) request that is invalid.
500 Internal Server Error	Signals some other error

Response Data

Response data is sent as either XML or JSON, depending on the type of data requested.

Request Data

POST and PUT request data may be formatted as XML (application/xml) or JSON (application/json).

When sending data to Chargify (PUT and POST method requests), make sure you specify the HTTP Content-Type header accordingly or else you will trigger Cross Site Request Forgery protections.

For example, with curl:

curl -u <api_key>:x -H Content-Type:application/json --verbose --data-binary @subscription.json https://subdomain.chargify.com/subscriptions.json

When performing requests that do not send data to Chargify (i.e. GET or DELETE method requests) the type of data requested should be inferred from the URL suffix (i.e. either .xml or .json). If you are having difficulty, it cannot hurt to specify the type of data you accept via the HTTP Accept header, i.e.

curl -u <api_key>:x -H Accept:application/json --verbose https://subdomain.chargify.com/subscriptions.json

Recent Discussions

	11 Mar, 2010 03:19 AM	Clearing Site Data Doesn't Clear Revenue
	11 Mar, 2010 03:17 AM	Problem Creating a Subscription for a user for a Free Product
	11 Mar, 2010 02:58 AM	Receipt email always shows outstanding balance
	11 Mar, 2010 02:46 AM	Question about how Chargify creates/handles ARB in Auth.net
	11 Mar, 2010 02:45 AM	merchant accnt // billing options // API -- questions

Recent Articles

	User Management
	API: Charges
	Creating One Time Charges
	API User Guide
	Hosted Signup Page

Chargify Support