Using the API

The Recharge API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

The base URL for Recharge's rest API is https://api.rechargeapps.com

Data structure

Subscriptions are tied to a given address. Each customer can have multiple address objects (many-to-one) in a relationship.

Rate limits

In order to ensure the overall stability and security of the Recharge platform, we have implemented API rate limiting. By understanding how we use rate limiting, and how we manage your API requests, you will be able to optimize your application to work with our platform.

For detailed information about rate limiting, please see the following page:

API Rate Limits

Authentication

• ReCharge OAuth2 Strategy for OmniAuth 1.0. Repo: Github omniauth-recharge

• omniauth-recharge-rails-example - this example shows how to implement omniauth with ruby and rails.
  The project was created using ruby 2.4.1 and rails 5.1.3.. Repo: Github omniauth-recharge-rails-example

FAQ

General

Can I use Javascript and it’s frameworks or any other front-end code to call Recharge API?

No! It will disclose your token and all other confidential information to everyone on the front-end and would pose a direct security vulnerability with a high impact on Confidentiality, Integrity, and Availability. CVSS score 10.0

What is the time zone I am seeing in the results of my queries?

Our DB uses Eastern Time which will change from EDT (UTC -4) to EST (UTC -5) and vice versa. All the records that you will pull through API calls will be shown in this time zone, regardless of the one that is set on the computer that you are making the requests from.

Managing your data

Can I hard delete Customers, Addresses, Subscription etc. from my store, because I used it for some testing?

It’s only possible to delete certain things from your store ( e.g. Addresses that didn't have any charges). We advise our API users to create a test-store for testing purposes. We don’t support hard deleting anything from the stores for security & traceability reasons.

Error handling

Is there any way in which we can increase the rate limit?

The API call limit operates using a “leaky bucket” algorithm as a controller. This allows for infrequent bursts of calls and allows your app to continue to make an unlimited amount of calls over time. The bucket size is 40 calls (which cannot be exceeded at any given time), with a “leak rate” of 2 calls per second that continually empties the bucket. If your app averages 2 calls per second, it will never trip a 429 error (“bucket overflow”).

• If you do 2 requests per second * 60 seconds = 120 requests per minute

• if you do a burst of 39 requests out of 40 requests which looks like this 39/40. That means you are left only with 1 requests left, but with each second that you don’t do requests the number of available requests increases by 2 requests. So if you do 39/40 requests and wait 10 seconds you are now at 19/40. That being said, you can do 40 requests bursts at once and after every 10 seconds you do 20 more requests. By doing that you are able to do 160 requests per minute if you perfectly time everything.

Response objects

I know I have more than 250 objects that should be returned by my query but the response only contains 250? How can i get them all returned?

The limits set by Recharge are 250 objects per GET request, and 1 object
by POST or Update request.
If you are receiving more than 250 objects in your GET request, you will have to use pagination to display them all.

For example, if you do this:

     curl -i -H ‘X-Recharge-Access-Token: store_api_token’ \ -X GET 
     https://api.rechargeapps.com/subscriptions?page=1 after that page, 2, page 3… 

Just create a code that will iterate through pages, and if the page contains 250 objects, iterate to another page and count its objects.
If the page doesn’t have 250 objects, stop iteration and that’s the number of your objects. You can always use more parameters to sort your requests for example by adding ?status=Active&page=N that will get all your objects by parameters you pass in URL.