API Reference

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.

Related guides: Generate API tokens.



API and Platforms compatibility

Recharge offers hosted solutions and integrates with various ecommerce platforms to process recurring transactions with the setup of your choice. In order to be compatible with those platforms some of our API resources and endpoints may be limited in use to a subset of platforms. When that is the case we will flag with the help of tags the checkout/platform association for which that feature is compatible.
When there is no restriction of compatibility no tags will appear.
Below is a legend of the tags you may come across:


Tag Checkout solution Ecommerce platform
BigCommerce Recharge hosted BigCommerce
Custom Recharge hosted or API-first Custom
RCS Recharge hosted Shopify
SCI Shopify hosted Shopify

You may also come across other tags specifying regional restrictions (e.g. USA Only) or new releases (e.g. Alpha, Beta).



Intro image
Base URL
https://api.rechargeapps.com

Authentication

Recharge uses API keys to authenticate requests.

Each request to the API should contain an API token in the following header:

X-Recharge-Access-Token:store_api_token

Replace store_api_token with your API key.

All requests must be made over HTTPS.


API Token Scopes

Scopes can be set up from the API token edit page in Recharge to control the level of access of an API token.

The API currently supports the scopes below:

Write Read
write_orders read_orders
write_discounts read_discounts
write_webhooks read_webhooks
write_subscriptions read_subscriptions
write_customers read_customers
write_payments read_payments
write_batches read_batches
write_charges read_charges
store_info
GET /
curl -i -H 'X-Recharge-Access-Token: your_api_token' -X GET

Versioning

All requests will use your account API settings, unless you send a X-Recharge-Version header to specify the version.

Current API Versions
2021-11
2021-01

Extending responses

The include parameter allows to enrich the API response by including contextual data for many of the objects which contain pointers to peripheral objects in their response properties. By using the include request parameter you can get the details of said peripheral object rather than the id or pointer only.

You can include a single field by specifying a string of the field you want to enrich or multiple fields at once by specifying an array of all the fields you want to enrich.

For example, the Charge object has an associated Address. By default when querying for a Charge the API response will only contain the address_id. However if in the query you add ?include=addresses the API response will contains the full Address object details in the response. Equally if you want to get the details of both Address and Customer you can add ?include=addresses,customer and you will get a response which includes the details of both the Address and the Customer.

This is a powerful feature for optimising your API calls if you know you will need data from the enriched objects.

Resource Endpoints Supported include values
Address GET /addresses

GET /addresses/:id
customer metafields
Charge GET /charges

GET /charges/:id
meatafields
Customer GET /customers

GET /customers/:id
addresses, metafields
Orders GET /orders

GET /orders/:id
customer, metafields
Products GET /products

GET /products/:id
collections, metafields
Subscriptions GET /subscriptions

GET /subscriptions/:id
metafields

Errors

Recharge uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided ( e.g. a required parameter was omitted, a charge failed, etc ), and codes in the 5xx range indicate an error with Recharge’s servers.

200 - OK: Everything worked as expected.
204 - OK, Content Deleted: The server has successfully fulfilled the request and deleted the desired object and there is no content to send in the response body.
400 - Bad Request: The request was unacceptable, often due to a missing required parameter.
401 - Unauthorized: No valid API key was provided.
402 - Request Failed: The parameters were valid but the request failed.
404 - Not Found: The requested resource doesn’t exist.
405 - Method Not Allowed: The method is not allowed for this URI.
409 - Conflict: You will get this error when you try to send two requests to edit an address or any of its child objects at the same time, in order to avoid out of date information being returned.
422 - Unprocessable Entity: Data sent was malformed or the format was not valid
429 - Too Many Requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors: Something went wrong on Recharge’s end (these are rare).

Page Based Pagination

By default API calls will return 50 results. By using the limit parameter that can be increased to 250 results.

When there are more results than can fit on a page you may loop through the results by using the page parameter.

To request a page, include page as a parameter in the url.

E.g. https://api.rechargeapps.com/subscriptions?limit=250&page=1

The example to the right shows a loop through all Subscription by page.

With minor changes this example can be used for looping through any object type: Customers, Addresses etc.


NOTE:
Page based pagination deep into large data sets is not recommended due to performance degradation. To paginate deeper into a data set, we recommend exploring cursor pagination instead.
Example Request
# request the first page (page=1)
curl -i -H 'X-Recharge-Access-Token: your_api_token' -X GET https://api.rechargeapps.com/subscriptions?limit=250&page=1
# request next page of results (page=2)
curl -i -H 'X-Recharge-Access-Token: your_api_token' -X GET https://api.rechargeapps.com/subscriptions?limit=250&page=2
Example Response
id: 123
id: 456
# ... continues through 250 records
page: 1 result_size: 250

id: 567
id: 678
# ... continues through 250 records
page: 2 result_size: 250

id: 567
id: 678
# ... continues through only 10 records, no further pages needed
page: 3 result_size: 10

Cursor Pagination

By default API calls will return 50 results. By using the limit parameter that can be increased to 250 results. When there are more results than the current limit a cursor may be used to request additional results.

Cursor based pagination is the preferred method for looping through all records in a given data set, as it is more performant than specifying a page number along with number of results. This method also provides more assurance that you will receive all of the records in a given set.

Cursor based pagination works by providing a reference to a specific item in a list of sequential data which will represent the cursor, such as a numeric id. You can then specify whether you would like to query records starting before or starting after that item.

For convenience, the API provides a Link header in all responses for which there are further pages. This header contains both a next_cursor and previous_cursor link, which is just a URL with an encoded page_info parameter that contains any filters from your first call, as well as markers to let the API know where it left off and where to begin for the next call.


Supported endpoints for Link
GET /addresses
GET /async_batches
GET /async_batches/:id/tasks
GET /charges
GET /customers
GET /discounts
GET /orders
GET /products
GET /subscriptions

NOTE:
/charges requests which supply either the updated_at_min or created_at_min filter will not currently return a Link header.
Requests which contain a filter for ids, shopify_product_ids will not return a Link header.
Example Request
curl -i  -H 'X-Recharge-Access-Token: your_api_token' -X GET https://api.rechargeapps.com/charges?limit=10

# Link header is returned to indicate next / previous page of result set.  The rel="previous/next" will appear based on whether there are additional results for a particular result set.
#link: <https://api.rechargeapps.com/charges?page_info=eyJvZmZzZXQiOiAwLCAic3RhcnRpbmdfYmVmb3JlX2lkIjogMjI5NTM4MDUwLCAic3RhcnRpbmdfYWZ0ZXJfaWQiOiBudWxsLCAibGFzdF92YWx1ZSI6IDIyOTUzODA1MCwgImN1cnNvciI6IG51bGwsICJwYWdlX2luZm8iOiBudWxsLCAib3JkZXJfYnkiOiAiaWQtZGVzYyIsICJjdXJzb3JfZGlyIjogIm5leHQifQ==&limit=10>; rel="next", <https://api.rechargeapps.com/charges?page_info=eyJvZmZzZXQiOiAwLCAic3RhcnRpbmdfYWZ0ZXJfaWQiOiAyMzAxMTg3NTksICJsYXN0X3ZhbHVlIjogMjMwMTE4NzU5LCAiY3Vyc29yIjogbnVsbCwgInBhZ2VfaW5mbyI6IG51bGwsICJvcmRlcl9ieSI6ICJpZC1hc2MiLCAiY3Vyc29yX2RpciI6ICJwcmV2aW91cyJ9&limit=10>; rel="previous"

# request next page of results
curl -i     -H 'X-Recharge-Access-Token: your_api_token' -X GET https://api.rechargeapps.com/charges?page_info=eyJvZmZzZXQiOiAwLCAic3RhcnRpbmdfYmVmb3JlX2lkIjogMjI5NTM4MDUwLCAic3RhcnRpbmdfYWZ0ZXJfaWQiOiBudWxsLCAibGFzdF92YWx1ZSI6IDIyOTUzODA1MCwgImN1cnNvciI6IG51bGwsICJwYWdlX2luZm8iOiBudWxsLCAib3JkZXJfYnkiOiAiaWQtZGVzYyIsICJjdXJzb3JfZGlyIjogIm5leHQifQ==&limit=10

Sorting

The API supports sorting of results when using a GET request to retrieve a list. Sorting is achieved using a sort_by query parameter in the request URL. The sort_by value contains the parameter and sort direction for your results (ascending or descending), and available sort_by values vary between resources. The below table defines available sort_by options for commonly used resources.


Resource Supported sort_by_values
Address Default: id-desc
Options: id-asc id-desc updated_at-asc updated_at-desc
Async Batch Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc
Charge Default: id-asc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc charge_date-asc charge-date-desc
Customer Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Discount Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Metafield Default: id-desc
Options:id-asc id-desc updated_at-asc updated_at-desc
Onetime Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc updated_at-desc
Order Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc shipped_date-asc shipped_date-desc shipping_date-asc shipping_date-desc updated_at-asc updated_at-desc
Product Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc title-asc title-desc
Subscription Default: id-desc
Options: id-asc id-desc created_at-asc created_at-desc updated_at-asc updated_at-desc
Webhook Default: id-desc
Options: id-asc id-desc

Addresses

Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.

Endpoints
POST
/customers/{id}/addresses
GET
/addresses/{id}
PUT
/addresses/{id}
DELETE
/addresses/{id}
GET
/addresses
GET
/addresses/count
POST
/addresses/validate

Charges

A charge is the representation of a the financial transaction linked to the purchase of an item (past or future). It can be a transaction that was processed already or the representation of an upcoming transaction. A charge is linked to its corresponding Orders( one Order for pay as you go subscriptions and several for pre-paid). Order are created once the corresponding Charge is successful. After successful payment, the first order will be immediately submitted to the external platform if applicable (e.g. Shopify, BigCommerce).

Endpoints
GET
/charges/{id}
GET
/charges
GET
/charges/count
POST
/charges/{id}/change_next_charge_date
POST
/charges/{id}/skip
POST
/charges/{id}/unskip
POST
/charges/{id}/refund
POST
/charges/{id}/process
POST
/charges/{id}/capture_payment

The checkout resource allows to create unique checkout experiences.
We currently support Stripe, Apple Pay, Google Pay, and Braintree as payment processor.

Related guides: Mobile payments

Endpoints
POST
/checkouts
GET
/checkouts/{token}
POST
/checkouts
PUT
/checkouts/{token}
GET
/checkouts/{token}/shipping_rates
POST
/checkouts/{token}/charge

Customers

The Customer object holds account and billing information. Email is unique on the customer; no two customers for a store can have the same email. Address is the child of the customer object. There can be many child addresses on a customer, but only one parent customer per address.

Endpoints
POST
/customers
GET
/customers/{id}
PUT
/customers/{id}
DELETE
/customers/{id}
GET
/customers
GET
/customers/count
GET
/customers/{id}/payment_sources