API Reference

The Recharge API is primarily a REST API with some RPC endpoints to support common operations. It has predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods.

Related guides: Generate API tokens, Using the API



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
read_accounts
write_batches read_batches
write_charges read_charges
write_customers read_customers
write_discounts read_discounts
read_events
write_notifications
write_orders read_orders
write_payment_methods read_payment_methods
write_products read_products
write_subscriptions read_subscriptions
read_store
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.
You can use the same token to make calls to all versions. When no version is specified it will default to the default version on your store.

Existing API Versions Release notes
2021-11 2021-11 release notes
2021-01

Responses

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.
201 - OK: The request was successful, created a new resource, and resource created is in the body.
202 - OK: The request has been accepted and is in processing.
204 - OK: The server has successfully fulfilled the request 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.
403 - The request was authenticated but not authorized for the requested resource (permission scope error).
404 - Not Found: The requested resource doesn’t exist.
405 - Method Not Allowed: The method is not allowed for this URI.
406 - The request was unacceptable, or requesting a data source which is not allowed although permissions permit the request.
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.
415 - The request body was not a JSON object.
422 - The request was understood but cannot be processed due to invalid or missing supplemental information.
426 - The request was made using an invalid API version.
429 - The request has been rate limited.
500 - Internal server error.
501 - The resource requested has not been implemented in the current version but may be implemented in the future.
503 - A 3rd party service on which the request depends has timed out.

Extending responses

Our API endpoints and webhooks allow developers to extend responses with additional data in order to optimize calls, allowing for simpler and more efficient implementations.

The API supports including additional objects when using a GET request to retrieve a list or a GET request to retrieve a record by a specific id. This is achieved by using an include query parameter in the request URL. The include value contains the object or objects you want to include in the response of your request. On routes where multiple includes are available, you are able to pass multiple values separated by a comma (include=customer,metafields). The below table defines available include values for commonly used resources of the API.

Webhooks support included_objects on the topics listed below. Webhook included_objects accepts an array of supported values ("included_objects": [ "customer", "metafields"]). Specifying included_objects will return an enriched payload, containing the original resource and the associated included objects.

Resource Endpoints Webhook topics Supported include values Supported included_objects values
Addresses GET /addresses
GET /addresses/:id		 address/created
address/updated		 customer
discount
payment_methods (beta)
subscriptions		 customer
metafields
Charges GET /charges
GET /charges/:id		 charge/created
charge/failed
charge/max_retries_reached
charge/paid
charge/refunded
charge/uncaptured
charge/upcoming
charge/updated		 metafields metafields
Customers GET /customers
GET /customers/:id		 customer/activated
customer/created
customer/deactivated
customer/payment_method_updated
customer/updated		 addresses
metafields
payment_methods (beta)
subscriptions		 addresses
metafields
Orders GET /orders
GET /orders/:id		 order/cancelled
order/created
order/deleted
order/processed
order/upcoming
order/updated		 customer
metafields		 customer
metafields
Products GET /products
GET /products/:id		 product/created
product/deleted
product/updated		 collections
metafields		 collections
metafields
Subscriptions GET /subscriptions
GET /subscriptions/:id		 subscription/activated
subscription/cancelled
subscription/created
subscription/deleted
subscription/skipped
subscription/updated
subscription/unskipped
subscription/paused		 address
metafields		 metafields

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.

Please note that the only compatible filter allowed to be used with cursors is limit.


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
URL="https://api.rechargeapps.com/charges?limit=5"

response=$(curl -s -w "%{http_code}" 
    -H 'X-Recharge-Access-Token: your_api_token'  
    -H 'X-Recharge-Version: 2021-11'  
    -X GET $URL)

 content=$(sed '$ d' <<< "$response") # get all but the last line which contains the status code

# Display results
echo $content | jq "."

# parse next url
echo "Next URL"
next_cursor=$(jq ".next_cursor" <<< "${content}")

# Notice next_cursor value is passed as page_info query param
echo "$URL&page_info=$next_cursor"

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
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
Expand

Charges

A charge is the representation of a 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
Expand

Checkouts

Pro plan

BigCommerce

Custom

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

Important - The Checkout endpoints are only available for BigCommerce and Custom. Checkouts on Shopify must go through Shopify.

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

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
Expand

Discounts

Discounts can be applied to checkout, or can be applied directly to an address. Depending on configuration they allow for single use, or recurring discounts.

Often discounts can be used combination with webhooks, such that when a specific event comes, it can apply a discount dependent on custom business logic.

There are various options that can be utilized for discounts such as minimum price, single use, recurring for a set number of charges, or ongoing. You can also set the date from which time the discount will become applicable begin, and when it can no longer be applied to a new subscription.

Endpoints
POST
/discounts
GET
/discounts/{id}
PUT
/discounts/{id}
DELETE
/discounts/{id}
GET
/discounts
GET
/discounts/count
POST
/addresses/{id}/apply_discount
POST
/charges/{id}/apply_discount
POST
/addresses/{id}/remove_discount
Expand

Metafields

BigCommerce

Custom

RCS

We now have metafields endpoint on our API!

Metafields feature allows you to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information.

Endpoints
POST
/metafields
GET
/metafields/{id}
PUT
/metafields/{id}
DELETE
/metafields/{id}
GET
/metafields
GET
/metafields/count
Expand

Notifications

The Customer Notifications API is used to dispatch email notifications to customers within Recharge. The API uses your configured Recharge email templates, and will dispatch an email to the address associated with the indicated customer_id. Some email templates require variable values, which are sent through the Customer Notifications API via the template_vars attribute. See below examples for all available template types.

Currently, the Customer Notifications API can be used to dispatch Get Account Access, and Upcoming Charge emails. Support for additional email templates and message types will be added in the future. To view your email template configurations, see the Notifications Settings section in your Recharge Merchant Portal.

Endpoints
POST
/customers/{id}/notifications
Expand

Onetimes

Onetimes represent non-recurring line items on a QUEUED Charge.

Endpoints
POST
/addresses/{address_id}/onetimes
GET
/onetimes/{id}
PUT
/onetimes/{id}
DELETE
/onetimes/{id}
GET
/onetimes
Expand

Orders

An order is created after a charge is successfully processed. The order contains all the same json data as the charge. In case of a prepaid order creation, the order will be queued for a particular date and submitted on that date to shopify.

Endpoints
GET
/orders/{id}
PUT
/orders/{id}
DELETE
/orders/{id}
GET
/orders
GET
/orders/count
POST
/orders/{id}/change_date
PUT
/orders/{id}/update_shopify_variant/{remote_variant_id}
POST
/orders/clone_order_on_success_charge/{order_id}/charge/{charge_id}
POST
/orders/{id}/delay
Expand

Products

The subscription settings associated to a remote catalog product

Endpoints
POST
/products
GET
/products/{id}
PUT
/products/{id}
DELETE
/products/{id}
GET
/products
GET
/products/count
Expand

Shop

The shop endpoint includes basic info about your Recharge store setup.

Endpoints
GET
/shop
GET
/shop/shipping_countries
Expand

Subscriptions

Subscriptions are individual items a customer receives on a recurring basis.

A subscription is a product added to an address.

If store owner wants to sell multiple products as one subscription on 1 address it can be done by creating a product in Shopify that consists of multiple products e.g. 3 types of vegetables in the box, set of different shirts, etc. This multiple products appear on the store as 1 product, therefore it can be sold in a single subscription to 1 or more addresses.

Endpoints
POST
/subscriptions
GET
/subscriptions/{id}
PUT
/subscriptions/{id}
DELETE
/subscriptions/{id}
GET
/subscriptions
GET
/subscriptions/count
POST
/subscriptions/{id}/set_next_charge_date
POST
/subscriptions/{id}/change_address
POST
/subscriptions/{id}/cancel
POST
/subscriptions/{id}/activate
POST
/addresses/{id}/subscriptions-bulk
PUT
/addresses/{id}/subscriptions-bulk
DELETE
/addresses/{id}/subscriptions-bulk

The subscription object

These fields are deprecated, however they will not be removed from this API version.
product_title is deprecated. Use title instead.
shipping_date is deprecated. Use scheduled_at instead.
shopify_id is deprecated. Use shopify_order_id instead.
address_is_active is deprecated. Please ignore, not an applicable field.

Attributes
  • id
    integer

    Unique numeric identifier for the subscription.

  • address_id
    integer

    Unique numeric identifier for the address the subscription is associated with.

  • cancellation_reason
    string

    Reason provided for cancellation.

  • cancellation_reason_comment
    string

    Additional comment for cancellation.

  • cancelled_at
    string

    The time the subscription was cancelled.

  • charge_interval_frequency
    string

    The number of units (specified in order_interval_unit) between each charge. For example, order_interval_unit=month and charge_interval_frequency=3, indicate charge every 3 months. Charges must use the same unit types as orders. Max value: 1000

  • created_at
    string

    The time the subscription was created.

  • customer_id
    integer

    Unique numeric identifier for the customer the subscription is tied to.

  • email
    string

    The email address of the customer.

  • expire_after_specific_number_of_charges
    integer

    Set the number of charges until subscription expires.

  • has_queued_charges
    boolean

    Retrieves 1 if there is queued charge. Otherwise, retrieves 0.

  • is_prepaid
    boolean

    Value is set to True if it is a prepaid item.

  • is_skippable
    boolean

    Value is set to True if it is not a prepaid item

  • is_swappable
    boolean

    Value is set to True if it is not a prepaid item and if in Customer portal settings swap is allowed for customers.

  • max_retries_reached
    boolean

    Retrieves 1 if charge has an error max retries reached. Otherwise, retrieves 0.

  • next_charge_scheduled_at
    string

    Date of the next charge for the subscription.

  • order_day_of_month
    integer

    The set day of the month order is created. Default is that there isn’t a strict day of the month when the order is created. This is only applicable to subscriptions with order_interval_unit = “month”.

  • order_day_of_week
    integer

    The set day of the week order is created. Default is that there isn’t a strict day of the week order is created. This is only applicable to subscriptions with order_interval_unit = “week”. Value of 0 equals to Monday, 1 to Tuesday etc.

  • order_interval_frequency
    string

    The number of units (specified in order_interval_unit) between each order. For example, order_interval_unit=month and order_interval_frequency=3, indicate order every 3 months. Max value: 1000

  • order_interval_unit
    string

    The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.

  • price
    integer

    The price of the item before discounts, taxes, or shipping have been applied.

  • product_title
    string

    The name of the product in a shop’s catalog.

  • properties
    string

    A list of line item objects, each one containing information about the subscription. Custom key-value pairs can be installed here, they will appear on the connected queued charge and after it is processed on the order itself.

  • quantity
    integer

    The number of items in the subscription.

  • recharge_product_id
    integer

    Unique number identifier of the product in Recharge.

  • shopify_product_id
    integer

    Unique number identifier of the product in Shopify.

  • shopify_variant_id
    integer

    Unique number identifier of the product variant in Shopify.

  • sku
    string

    A unique identifier of the item in the fulfillment. In cases where SKU is blank, it will be dynamically pulled whenever it is used.

  • sku_override
    boolean

    Flag that is automatically updated to true when SKU is passed on create or update. When sku_override is true, the sku on the subscription will be used to generate charges and orders. When sku_override is false, Recharge will dynamically fetch the SKU from the corresponding shopify variant.

  • status
    string

    The status of the subscription. Valid values:

    • ACTIVE - The subscription is active.
    • CANCELLED - The subscription has been cancelled.
    • EXPIRED - The subscription has expired. This occurs when the maximum number of charges for a product has been reached.

  • variant_title
    string

    The name of the variant in a shop’s catalog.

The subscription object
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Create a subscription

When creating a subscription via API, “order_interval_frequency” and “charge_interval_frequency” values do not necessarily need to match the values set in the respective ruleset. The product, however, does need to be a part of a ruleset in order to be added to a subscription.

Scopes: write_subscriptions
Body Parameters
  • address_id
    integer
    * Required

    Unique numeric identifier of the customer’s address.

  • charge_interval_frequency
    integer
    * Required

    The number of units, specified in order_interval_unit, between each charge.

  • customer_id
    string

    Unique numeric identifier of the customer.

  • expire_after_specific_number_of_charges
    string

    The number of charges until the subscription expires.

  • next_charge_scheduled_at
    string
    * Required

    This will set the first charge date of a new subscription.

  • order_day_of_month
    string

    This is populated when order_interval_unit has value “month”. Default value is 0.

  • order_day_of_week
    string

    This is populated when order_interval_unit has value “week”.

  • order_interval_frequency
    string
    * Required

    The number of units, specified in order_interval_unit, between each order.

  • order_interval_unit
    string
    * Required

    The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.

  • price
    string

    The price of the product.

  • properties
    string

    The list of line item objects.

  • product_title
    string

    The name of the product.

  • quantity
    string
    * Required

    The quantity of the product

  • shopify_product_id
    string
    * Required

    Unique numeric identifier of the product id in Shopify.

  • shopify_variant_id
    string
    * Required

    Unique numeric identifier of the product variant id in Shopify.

  • status
    string

    Default: ACTIVE

    Default is set to “ACTIVE”.

Responses
  • 200

    Success

    Show response object
POST
/subscriptions 
curl 'https://api.rechargeapps.com/subscriptions' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "address_id": 48563471,
  "charge_interval_frequency":"30",
  "next_charge_scheduled_at":"2020-07-15",
  "order_interval_frequency":"15",
  "order_interval_unit":"day",
  "properties": [
    {
      "name": "Colour",
      "value": "Yellow"
    },
    {
      "name": "Bottle Material",
      "value": "Glass"
    }
  ]
  "shopify_variant_id":32165284380775,
  "shopify_product_id":4546063663207
  "quantity":3
}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Retrieve a subscription

Retrieve a subscription using the Recharge subscription id.

Scopes: read_subscriptions
Responses
  • 200

    Success

    Show response object
GET
/subscriptions/{id} 
curl 'https://api.rechargeapps.com/subscriptions/27363808' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Update a subscription

Update an existing subscription.

Updating parameters like frequency, charge_interval_frequency, order_interval_frequency, order_interval_unit will affect our algorithm to automatically recalculate the next charge date (next_charge_scheduled_at). If you want to change the next charge date (next_charge_scheduled_at) we recommend you to update these parameters first.

When updating subscription “status” attribute from “CANCELLED” to “ACTIVE”, following attributes will be set to null: “cancelled_at”, “cancellation_reason” and “cancellation_reason_comments”

When updating order_interval_unit OR order_interval_frequency OR charge_interval_frequency all three parameters are required

Scopes: write_subscriptions
Query Parameters
  • force_update
    boolean

    If set to True, updates will also be applied to CANCELLED subscriptions. If null or False, only ACTIVE subscriptions will be updated.

Body Parameters
  • charge_interval_frequency
    string
    * Required

    The number of units (specified in order_interval_unit) between each charge. Required when updating order_interval_unit.

    WARNING: This update will remove skipped and manually changed charges.

  • commit_update
    boolean

    Controls whether the QUEUED charges linked to the subscription should be regenerated upon subscription update. By default the flag is set to true which means the charges get regenerated for every PUT. Having the flag set to false will delay charge regeneration 5 seconds so you can run multiple calls to perform the changes and you’ll be able to receive responses much faster since your app won’t wait between requests and responses for every charge regeneration to complete.

  • expire_after_specific_number_of_charges
    string

    The number of charges until subscription expires.

  • order_day_of_month
    string

    The day of the month the order is created on.

    WARNING: this update will remove skips and manually changed charges.

  • order_day_of_week
    string

    The day of the week the order is created on.

    WARNING: this update will remove skips and manually changed charges.

  • order_interval_frequency
    string
    * Required

    The number of units (specified in order_interval_unit) between each order. Required when updating order_interval_unit.

    WARNING: This update will remove skipped and manually changed charges.

  • order_interval_unit
    string
    * Required

    The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.

    WARNING: This update will remove skipped and manually changed charges.

  • override
    string

    Advanced usage only When used, this allows for updating a prepaid subscription variant, which otherwise is not allowed because of the complexity of results. Use with caution.

  • price
    string

    The price of the item before discounts, taxes, or shipping has been applied.

  • product_title
    string

    The name of the product.

  • properties
    string

    List of properties.

  • quantity
    string

    The number of items in the subscription.

  • shopify_variant_id
    string

    [Swap Product (NEW)][1]
    Unique number identifier of the product variant in Shopify.

  • sku
    string

    A unique identifier of the item in the fulfillment.

  • sku_override
    string

    Flag is automatically updated to true when SKU is passed on create or update. When sku_override is true, the sku on the subscription will be used to generate charges and orders. When sku_override is false, Recharge will dynamically fetch the sku from the corresponding shopify variant.

  • use_shopify_variant_defaults
    boolean

    Flag instructing to pull the price, sku, variant_title, and product_title from the provided Shopify variant.

    You need to pass the variant_id and set this attribute to true in the request for the flag to work.

  • variant_title
    string

    The name of the product variant.

Responses
  • 200

    Success

    Show response object
PUT
/subscriptions/{id} 
curl -X PUT 'https://api.rechargeapps.com/subscriptions/27363808' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -H 'Content-Type: application/json' \ 
 -d '{"quantity": 4}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Delete a subscription

We now have a feature for deleting a subscription.

Scopes: write_subscriptions
Body Parameters
  • send_email
    boolean

    When your store setting indicates that cancellation emails should be sent, this value determines if the email should be sent for the specified subscription cancellation. If set to 1, cancellation emails will be sent for the specified subscription cancellations. If set to 0, cancellation emails will not be sent.

Responses
  • 200

    successful response

    Show response object
DELETE
/subscriptions/{id} 
curl -X DELETE -H 'https://api.rechargeapps.com/subscriptions/89559201' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{}

List subscriptions

Returns a list of all your subscriptions.


## HTTP request examples

GET /subscriptions
GET /subscriptions?created_at_min=2018-10-10&created_at_max=2019-10-16
GET /subscriptions?customer_id=<customer_id>

Scopes: read_subscriptions
Query Parameters
  • address_id
    string

    Return the subscriptions linked to the given address id.

  • created_at_max
    string

    Return the subscriptions created before the given date.

  • created_at_min
    string

    Return the subscriptions created after the given date.

  • customer_id
    string

    Return the subscriptions linked to the given Recharge customer id.

  • ids
    string

    Comma-separated list of subscription ids to filter

  • include_onetimes
    string

    (beta-feature)
    When set as true the response will contain onetimes and subscriptions that meet the given search criteria. Onetimes will be sent as an array with the key “onetimes” and subscriptions will be sent as an array with the key “subscriptions”. If no onetimes or subscriptions meet the search criteria, the corresponding array will be empty. Requires one of the following search parameters:

    * address_id
    * customer_id
    * shopify_customer_id

    Note: this feature requires a beta flag that must be enabled by Recharge.

  • limit
    string

    Default: 50

    Max: 250

    The number of results. Default value is 50 and maximum is 250.

  • page
    string

    Default: 1

    The page to show. Default value is 1.

  • shopify_customer_id
    string

    Return the subscriptions linked to the given Shopify customer id.

  • shopify_variant_id
    string

    Return the subscriptions linked to the given Shopify product variant id.

  • status
    string

    Return the subscriptions with specified status. Status can have the following values:

    • ACTIVE - The subscription is active.
    • CANCELLED - The subscription has been cancelled.
    • EXPIRED - The subscription has expired. This occurs when the maximum number of charges for a product has been reached.

  • updated_at_max
    string

    Return the subscriptions updated before the given date.

  • updated_at_min
    string

    Return the subscriptions updated after the given date.

Responses
  • 200

    successful response

    Show response object
GET
/subscriptions 
curl https://api.rechargeapps.com/subscriptions
 -H 'X-Recharge-Access-Token: your_api_token'
 -d limit=3 -Gcurl https://api.rechargeapps.com/subscriptions -H 'X-Recharge-Access-Token: your_api_token' -d limit=3 -G
curl -X DELETE -H https://api.rechargeapps.com/subscriptions/89559201 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "subscriptions": [
    {
      "id": 89560571,
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "30",
      "created_at": "2020-07-10T10:39:01",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": null,
      "has_queued_charges": 1,
      "is_prepaid": false,
      "is_skippable": true,
      "is_swappable": false,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-07-16T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "30",
      "order_interval_unit": "day",
      "price": 7,
      "product_title": "Orange Juice Auto renew",
      "properties": [],
      "quantity": 2,
      "recharge_product_id": 1463299,
      "shopify_product_id": 4578081833063,
      "shopify_variant_id": 32309455192167,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:01",
      "variant_title": "Squeezed"
    }
  ]
}

Count subscriptions

Returns the count of subscriptions.


## HTTP request examples

GET /subscriptions/count
GET /subscriptions/count?customer_id=123123123
GET /subscriptions/count?address_id=123123123
GET /subscriptions/count?status=ACTIVE
GET /subscriptions/count?shopify_customer_id=123123123123
GET /subscriptions/count?shopify_variant_id=123123123123
GET /subscriptions/count?updated_at_min=2019-11-10-&updated_at_max=2019-11-11
GET /subscriptions/count?created_at_min=2019-11-10-&updated_at_max=2019-11-11

Scopes: read_subscriptions
Query Parameters
  • address_id
    string

    Return the count of subscriptions linked to the given address id.

  • created_at_max
    string

    Return the count of subscriptions created before the given date.

  • created_at_min
    string

    Return the count of subscriptions created after the given date.

  • customer_id
    string

    Return the count of subscriptions linked to the given customer id.

  • shopify_customer_id
    string

    Return the count of subscriptions linked to the given Shopify customer id.

  • shopify_variant_id
    string

    Return the count of subscriptions that have the provided shopify_variant_id

  • status
    string

    Return the count of subscriptions with specified status. Status can have the following values:

    • ACTIVE - The subscription is active.
    • CANCELLED - The subscription has been cancelled.
    • EXPIRED - The subscription has been expired. This occurs when the maximum number of charges for a product has been reached.

  • updated_at_max
    string

    Return the count of subscriptions updated before the given date.

  • updated_at_min
    string

    Return the count of subscriptions updated after the given date.

Responses
  • 200

    successful response

    Show response object
GET
/subscriptions/count 
curl 'https://api.rechargeapps.com/subscriptions/count' \ 
 -H 'X-Recharge-Access-Token: your_api_token'
Response 
{
  "count": 120457
}

Change a subscription next charge date

Update an existing subscription’s next charge date.

Note: if there are two active subscriptions with the same address_id, and you update their next_charge_date parameters to match, their charges will get merged into a new charge with a new id

Scopes: write_subscriptions
Body Parameters
  • date
    string
    * Required

    The next charge date desired.

Responses
  • 200

    Success

    Show response object
POST
/subscriptions/{id}/set_next_charge_date 
curl 'https://api.rechargeapps.com/subscriptions/27363808/set_next_charge_date' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"date": "2021-08-05"}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Change a subscription address

Update an existing subscription’s address.

Scopes: write_subscriptions
Body Parameters
  • address_id
    string
    * Required

    Unique id of the address that need to be associated with subscription.

  • next_charge_scheduled_at
    string

    Date and time when next charge need to be scheduled.

Responses
  • 200

    Success

    Show response object
POST
/subscriptions/{id}/change_address 
curl 'https://api.rechargeapps.com/subscriptions/27363808/change_address' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"address_id": 23397943}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Cancel a subscription

Cancel an active subscription.

An involuntary subscription cancelled due to max retries reached will trigger the charge/max_retries_reached webhook. If this leads to the subscription being cancelled, the subscription/cancelled webhook will trigger.

Scopes: write_subscriptions
Body Parameters
  • cancellation_reason
    string
    * Required

    Reason for subscription cancellation.

  • cancellation_reason_comments
    string

    Cancellation reason comment. Maximum length is 1024 characters.

  • send_email
    string

    If set to false, subscription cancelled email will not be sent to customer and store owner. Note: even if set to True, there are some conditions where an email will not be sent. They are: inactive subscription_cancellation email template, customer or subscription was created on the same day, subscription is for a membership, email already sent for this subscription in the last 24 hours, customer has other active subscriptions or onetimes

Responses
  • 200

    Success

    Show response object
POST
/subscriptions/{id}/cancel 
curl 'https://api.rechargeapps.com/subscriptions/27363808/cancel' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{"cancellation_reason": "other reason"}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Activate a subscription

Activate a cancelled subscription.

When activating subscription, following attributes will be set to null: “cancelled_at”, “cancellation_reason” and “cancellation_reason_comments”

Scopes: write_subscriptions
Responses
  • 200

    Success

    Show response object
POST
/subscriptions/{id}/activate 
curl 'https://api.rechargeapps.com/subscriptions/27363808/activate' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your api token' \ 
 -d '{}'
Response 
{
  "subscription": {
    "id": 89559201,
    "address_id": 48563471,
    "analytics_data": {
      "utm_params": []
    },
    "cancellation_reason": null,
    "cancellation_reason_comments": null,
    "cancelled_at": null,
    "charge_interval_frequency": "30",
    "created_at": "2020-07-10T10:30:51",
    "customer_id": 43845860,
    "email": "example@email.com",
    "expire_after_specific_number_of_charges": null,
    "has_queued_charges": 1,
    "is_prepaid": true,
    "is_skippable": false,
    "is_swappable": false,
    "max_retries_reached": 0,
    "next_charge_scheduled_at": "2020-07-15T00:00:00",
    "order_day_of_month": null,
    "order_day_of_week": null,
    "order_interval_frequency": "15",
    "order_interval_unit": "day",
    "price": 5,
    "product_title": "Powder Milk 50.00% Off Auto renew",
    "properties": [
      {
        "name": "Colour",
        "value": "White"
      },
      {
        "name": "Package Material",
        "value": "Paper"
      }
    ],
    "quantity": 3,
    "recharge_product_id": 1422079,
    "shopify_product_id": 4546063663207,
    "shopify_variant_id": 32165284380775,
    "sku": null,
    "sku_override": false,
    "status": "ACTIVE",
    "updated_at": "2020-07-10T10:30:51",
    "variant_title": "1 / Powder"
  }
}

Bulk create subscriptions

Bulk create new subscriptions.

There is a limit of 20 subscriptions per request.

Scopes: write_subscriptions
Body Parameters
  • charge_interval_frequency
    string
    * Required

    The number of units, specified in order_interval_unit, between each charge.

  • customer_id
    string

    Unique numeric identifier of the customer.

  • expire_after_specific_number_of_charges
    string

    The number of charges until subscription expires.

  • next_charge_scheduled_at
    string
    * Required

    This will set the first charge date of a new subscription.

  • order_day_of_month
    string

    This is populated when order_interval_unit has value “month”. Default value is 0.

  • order_day_of_week
    string

    This is populated when order_interval_unit has value “week”.

  • order_interval_frequency
    string

    The number of units, specified in order_interval_unit, between each order.

  • order_interval_unit
    string
    * Required

    The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.

  • price
    string

    The price of the product.

  • product_title
    string

    The name of the product.

  • properties
    string

    The list of line item objects.

  • quantity
    string
    * Required

    The quantity of the product.

  • shopify_variant_id
    string
    * Required

    Unique numeric identifier of the product variant in Shopify.

  • status
    string

    Default: ACTIVE

    Default is set to “ACTIVE”.

Responses
  • 200

    Success

    Show response object
POST
/addresses/{id}/subscriptions-bulk 
curl 'https://api.rechargeapps.com/addresses/42420080/subscriptions-bulk' \ 
 -H 'Content-Type: application/json' \ 
 -H 'X-Recharge-Access-Token: your_api_token' \ 
 -d '{
  "subscriptions":
    [
      {
        "charge_interval_frequency": "30",
        "next_charge_scheduled_at": "2020-07-16",
        "order_interval_frequency": "30",
        "order_interval_unit": "day",
        "quantity": 2,
        "shopify_variant_id": 32309455192167
      },
      {
        "charge_interval_frequency": "6",
        "expire_after_specific_number_of_charges": 4,
        "next_charge_scheduled_at": "2020-07-13",
        "order_interval_frequency": "1",
        "order_interval_unit": "month",
        "quantity": 1,
        "shopify_variant_id": 32309455224935
      },
      {
        "charge_interval_frequency": "4",
        "next_charge_scheduled_at": "2020-08-01",
        "order_interval_frequency": "4",
        "order_interval_unit": "week",
        "quantity": 1,
        "shopify_variant_id": 32165284479079
      }
    ]
}'
Response 
{
  "subscriptions": [
    {
      "id": 89560571,
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "30",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": null,
      "has_queued_charges": 1,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-07-16T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "30",
      "order_interval_unit": "day",
      "price": 7,
      "product_title": "Orange Juice Auto renew",
      "properties": [],
      "quantity": 2,
      "recharge_product_id": 1463299,
      "shopify_product_id": 4578081833063,
      "shopify_variant_id": 32309455192167,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "Squeezed"
    },
    {
      "id": 89560572,
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "6",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": 4,
      "has_queued_charges": 1,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-07-13T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "1",
      "order_interval_unit": "month",
      "price": 7,
      "product_title": "Orange Juice Auto renew",
      "properties": [],
      "quantity": 1,
      "recharge_product_id": 1463299,
      "shopify_product_id": 4578081833063,
      "shopify_variant_id": 32309455224935,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "Can"
    },
    {
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "4",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": null,
      "has_queued_charges": 1,
      "id": 89560574,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-08-01T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "4",
      "order_interval_unit": "week",
      "price": 5,
      "product_title": "Powder Milk 50.00% Off Auto renew",
      "properties": [],
      "quantity": 1,
      "recharge_product_id": 1422079,
      "shopify_product_id": 4546063663207,
      "shopify_variant_id": 32165284479079,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "1 / Powder"
    }
  ]
}

Bulk update subscriptions

Bulk update existing subscriptions

There is a limit of 20 subscriptions per request.

Updating parameters like frequency, charge_interval_frequency, order_interval_frequency, and order_interval_unit will affect our algorithm to automatically recalculate the next charge date (next_charge_scheduled_at). If you want to change the next charge date (next_charge_scheduled_at) we recommend you update these parameters first.

When updating the subscription status attribute from CANCELLED to ACTIVE, the following attributes will be set to null: cancelled_at, cancellation_reason, and cancellation_reason_comments.

When updating order_interval_unit OR order_interval_frequency OR charge_interval_frequency, all three parameters are required.

Scopes: write_subscriptions
Body Parameters
  • id
    string
    * Required

    Unique identifier of subscription.

  • address_id
    string

    Can be used to change the address of the subscriptions.

  • cancellation_reason
    string

    Used to provide cancellation reason when cancelling subscriptions.

  • cancellation_reason_comments
    string

    If cancellation_reason is provided, this attribute can be used to provide additional cancellation reason comments. Maximum length is 1024 characters.

  • charge_interval_frequency
    string
    * Required

    The number of units (specified in order_interval_unit) between each charge. Required when updating order_interval_unit.

    WARNING: This update will remove skipped and manually changed charges.

  • expire_after_specific_number_of_charges
    string

    The number of charges until the subscription expires.

  • force_update
    boolean

    If set to True, updates will also be applied to CANCELLED subscriptions. If null or False, only ACTIVE subscriptions will be updated.

  • next_charge_scheduled_at
    string
    * Required

    Can be used to change the date of the next queued charge (must be current or future date).

  • order_day_of_month
    string

    The day of the month order is created.

    WARNING: this update will remove skips and manually changed charges.

  • order_day_of_week
    string

    The day of the week order is created.

    WARNING: this update will remove skips and manually changed charges.

  • order_interval_frequency
    string

    The number of units (specified in order_interval_unit) between each order. Required when updating order_interval_unit.

    WARNING: This update will remove skipped and manually changed charges.

  • order_interval_unit
    string
    * Required

    The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.

    WARNING: This update will remove skipped and manually changed charges.

  • price
    string

    The price of the item before discounts, taxes, or shipping has been applied.

  • product_title
    string

    The name of the product.

  • properties
    string

    List of properties.

  • quantity
    string

    The number of items in subscription.

  • send_email
    string

    If set to false, subscription cancelled email will not be sent to customer and store owner.

  • shopify_variant_id
    string

    [Swap Product (NEW)][1]
    Unique number identifier of the product variant in Shopify.

  • sku
    string

    A unique identifier of the item in the fulfillment.

  • sku_override
    string

    Flag is automatically updated to true when SKU is passed on create or update. When sku_override is true, the sku on the subscription will be used to generate charges and orders. When sku_override is false, Recharge will dynamically fetch the sku from the corresponding shopify variant.

  • use_shopify_variant_defaults
    boolean

    Flag instructing to pull the price, sku, variant_title, and product_title from the provided Shopify variant.

    You need to pass the variant_id and set this attribute to true in the request for the flag to work.

  • status
    string

    Status of the subscription. Can be used to cancel subscriptions when set to CANCELLED or to re-activate subscriptions when set to ACTIVE.

  • variant_title
    string

    The name of the product variant.

Responses
  • 200

    Success

    Show response object
PUT
/addresses/{id}/subscriptions-bulk 
curl -X PUT https://api.rechargeapps.com/addresses/42420080/subscriptions-bulk
 -H 'Content-Type: application/json'
 -H 'X-Recharge-Access-Token: your_api_token'
 -d '{
  "subscriptions":
    [
      {
        "id": 64993717,
        "price": 23.00,
        "quantity": 3
      },
      {
        "id": 64993718,
        "price": 24.00,
        "quantity": 4
      },
      {
        "id": 64993719,
        "price": 25.00,
        "quantity": 5
      }
    ]
}'
Response 
{
  "subscriptions": [
    {
      "id": 89560571,
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "30",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": null,
      "has_queued_charges": 1,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-07-16T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "30",
      "order_interval_unit": "day",
      "price": 7,
      "product_title": "Orange Juice Auto renew",
      "properties": [],
      "quantity": 2,
      "recharge_product_id": 1463299,
      "shopify_product_id": 4578081833063,
      "shopify_variant_id": 32309455192167,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "Squeezed"
    },
    {
      "id": 89560572,
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "6",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": 4,
      "has_queued_charges": 1,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-07-13T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "1",
      "order_interval_unit": "month",
      "price": 7,
      "product_title": "Orange Juice Auto renew",
      "properties": [],
      "quantity": 1,
      "recharge_product_id": 1463299,
      "shopify_product_id": 4578081833063,
      "shopify_variant_id": 32309455224935,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "Can"
    },
    {
      "address_id": 48563471,
      "analytics_data": {
        "utm_params": []
      },
      "cancellation_reason": null,
      "cancellation_reason_comments": null,
      "cancelled_at": null,
      "charge_interval_frequency": "4",
      "created_at": "2020-07-10T10:39:00",
      "customer_id": 43845860,
      "email": "example@email.com",
      "expire_after_specific_number_of_charges": null,
      "has_queued_charges": 1,
      "id": 89560574,
      "max_retries_reached": 0,
      "next_charge_scheduled_at": "2020-08-01T00:00:00",
      "order_day_of_month": null,
      "order_day_of_week": null,
      "order_interval_frequency": "4",
      "order_interval_unit": "week",
      "price": 5,
      "product_title": "Powder Milk 50.00% Off Auto renew",
      "properties": [],
      "quantity": 1,
      "recharge_product_id": 1422079,
      "shopify_product_id": 4546063663207,
      "shopify_variant_id": 32165284479079,
      "sku": null,
      "sku_override": false,
      "status": "ACTIVE",
      "updated_at": "2020-07-10T10:39:00",
      "variant_title": "1 / Powder"
    }
  ]
}

Bulk delete subscriptions

Bulk delete subscriptions.

There is a limit of 20 subscriptions per request.

Scopes: write_subscriptions
Body Parameters
  • id
    integer
    * Required

    Unique identifier of subscription.

  • send_email
    boolean

    When your store setting indicates that cancellation emails should be sent, this value determines if subscription cancellation emails should be sent. If set to 1, cancellation emails will be sent for each of the specified subscriptions. If set to 0, cancellation emails will not be sent for any of the specified subscriptions.

Responses
  • 200

    successful response

    Show response object
DELETE
/addresses/{id}/subscriptions-bulk 
curl -X DELETE https://api.rechargeapps.com/addresses/42420080/subscriptions-bulk
 -H 'X-Recharge-Access-Token: your_api_token'
 -d '{
  "subscriptions":
    [
      {
        "id": 64993717
      },
      {
        "id": 64993718
      },
      {
        "id": 64993719
      }
    ],
    "send_email":0
  }'
Response 
{
  "subscriptions": []
}

Webhook endpoints

Webhooks are a mechanism for reacting to specific events that are triggered in the Recharge system.
For example, a checkout completion, a customer activation or subscription cancellation. Webhooks will deliver you the data of the specific event in real-time. This data can be used to custom code logic behind automated subscription management, dashboards creation, discounts applying…


Retries / Idempotency
Due to webhook retries, it’s possible that your application receives the same webhook more than once. Ensure idempotency of the webhook call by detecting such duplicates within your application.


When a webhook is triggered, the payload will be identical to the payload you would receive from another API endpoint.

For example, a webhook on subscription/created event will be identical to the payload for retrieving a subscription by ID from the Recharge API.

There are a lot of things that can be done via Webhooks: It can be used to collect all kinds of data from our API and then create custom a Dashboard to show how much and when your customers are buying in real time, or use all this data to do Analytics of some kind in order to create a better customer experience. Webhooks can be used as a “Trigger” on your backend to update subscription products.

If you have some kind of a Subscription where you want to change the Product that the customer gets every month, you can do it by waiting for an order/created webhook on your backend, and when it fires you can make an API call to change the Product of that subscription or the next shipping date, etc.


## Respond to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Recharge know that you didn’t receive your webhook. Recharge has implemented a 5 second time-out period. We wait 5 seconds, if our system doesn’t get a response in that period we consider that request as failed. Our system will try 20 times to send the same webhook over the next 2 days, if the request fails every time our system will delete this webhook. At this moment our system is logging those deleted webhooks.

Endpoints
POST
/webhooks
GET
/webhooks/{id}
PUT
/webhooks/{id}
DELETE
/webhooks/{id}
GET
/webhooks
POST
/webhooks/{id}/test
Expand

Webhooks explained

Here you will find what specific action triggers a given webhook.


Address webhooks

To use these webhooks your API Token must have read permissions for Customers enabled ( read_customer ).


Topic Explanation
address/created This will trigger when you create an address via API, or when you go through the checkout with a particular address for the first time with the same customer.
address/updated This will trigger when you update an address via API, or when you update the address via UI. It will also trigger whenever a subscription has been activated or cancelled.

Charge webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read_orders ).


Topic Explanation
charge/created This will trigger when your customers checkout successfully (only on the UI checkout success).
charge/failed This will trigger every time we try to process a charge and it fails due to various reasons (insufficient funds, invalid CC info, expired CC, etc.) on both API and UI.
charge/max_retries_reached This will trigger after we attempt to process a charge 8 times, and it failed every time due to various CC issues. This can be triggered on both UI (manually retry a charge 8 times and fail) and API.
charge/paid This will trigger when a charge is successfully processed, both manually via UI and automatic recurring charge. This will not trigger on the checkout itself.
charge/refunded This will trigger when a charge is successfully refunded, either partially or in full. It will fire if a charge has been refunded both manually via UI and through an API request.
charge/upcoming This will trigger X days before the upcoming charge is scheduled. The default is 3 days but your store specific setting can be verified on the Notification Settings page in the description of the Upcoming charge customer notification.
charge/updated This will trigger when applying a discount, a change to charge that recalculates shipping rates as well as if next_charge_date is updated on charge endpoint charges/<charge_id>/change_next_charge_date.
charge/deleted This will trigger when a subscription is cancelled and upcoming charges are deleted.

Checkout webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read-orders ).


Topic Explanation
checkout/created This will trigger when a checkout is successfully created.
checkout/completed Will be deprecated.
checkout/processed This will trigger when a checkout is successfully processed.
checkout/updated This will trigger when a checkout is successfully updated.

Customer webhooks

To use these webhooks your API Token must have read permissions for Customers enabled ( read_customers ).


Topic Explanation
customer/activated This will trigger when you activate* a customer
* activating means that you have added a subscription to a customer who didn’t have an active subscription previously.
customer/created This will trigger when you create a customer via API or go through the checkout with a particular email address for a first time customer.
customer/deactivated This will trigger when the last subscription a customer had expires, so he no longer has ANY active subscriptions (which means there are no QUEUED charges/orders for this customer).
customer/payment_method_updated This will trigger only* when you update the payment_token from the UI
* We are working on triggering this when you do the update from the API as well.
customer/updated This will trigger when you update a customer via both API and UI.
customer/deleted This will trigger when you delete a customer via both API and UI.

Onetime webhooks

To use these webhooks your API Token must have read permissions for Subscriptions enabled ( read_subscriptions ).


Topic Explanation
onetime/created This will trigger when you create a one time product via API.
onetime/deleted This will trigger when you delete a one time product via API.
onetime/updated This will trigger when you update a one time product via API.

Order webhooks

To use these webhooks your API Token must have read permissions for Orders enabled ( read_orders ).


Topic Explanation
order/created This will trigger when an order is created (when a charge is successfully processed)
* In case of prepaid Orders there will be multiple order/created webhooks fired, one for every queued order created at once.
order/deleted This will trigger when an order is deleted.
order/processed This will trigger when the order is processed (when an order goes from status queued to status success). This will not trigger on checkout.
order/upcoming This will trigger X days before a QUEUED (prepaid) order is scheduled to be processed. The default is 3 days.
order/updated This will trigger when an order is updated.

Plan webhooks

To use these webhooks your API Token must have read permissions for Products enabled ( read_products ).


Topic Explanation
plan/created This will trigger when a plan is created by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint.
plan/deleted This will trigger when a plan is deleted by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint.
plan/updated This will trigger when a plan is updated by one of the following methods: via API, via Merchant portal or when using the 2021-01 Products endpoint…

Subscription webhooks

To use these webhooks your API Token must have read permissions for Subscriptions enabled ( read_subscriptions ).


Topic Explanation
subscription/activated This will trigger when you activate a subscription via API or UI.
subscription/cancelled This will trigger when you cancel a subscription via API or UI. An involuntary subscription cancelled due to max retries reached will only trigger the charge/max_retries_reached webhook and not the subscription/cancelled webhook.
subscription/created This will trigger when you create a subscription via API or when you go through the checkout on UI.
subscription/deleted This will trigger when you delete a subscription via API or UI.
subscription/skipped This will trigger when you skip a subscription within a charge, meaning that you only skip a particular subscription (the subscription_id you send in the body) in that charge if there are multiple subscriptions related to that charge.
subscription/unskipped This will trigger when you unskip a subscription within a charge, meaning you only unskip a particular subscription (the subscription_id you send in the body) in that charge if there are multiple subscriptions related to that charge.
subscription/updated This will trigger when you update a subscription via API (PUT method) or when you update the subscription via UI. This will also trigger when you update next charge date on Customer Portal, or when you change it using subscription endpoint subscriptions/ <subscription_id>set_next_charge_date.
subscription/swapped This will trigger when you swap a subscription product for a given address to a different product or product variation API or UI.
subscription/paused This will trigger when a customer pauses a subscription from within the customer portal.

Other webhooks

To use these webhooks your API Token must have read permissions for Store enabled ( read_store ).


Topic Explanation
app/uninstalled This will trigger when you uninstall OAuth app on your store.
recharge/uninstalled This will trigger when Recharge is uninstalled.
store/updated This will trigger when and update has been made to the store.

Webhook validation

Webhooks created through the API can be verified by calculating a digital signature. Each Webhook request includes an X-Recharge-Hmac-Sha256 header which is generated using the API Client Secret, along with the data sent in the request.

API Client Secret is not the same as your API token and it can be found at:
Recharge Dashboard—>Integrations—>API Tokens—>Click on your token
Edit API Token page will appear and there you will find API Client Secret

The request_body must be in JSON string format. Validation will fail even if one space is lost in process of JSON string generation.

Then use code similar to the example by adapting it to the programming language that you are using for your project.

Related guides: Example code for validating webhooks

Example Request:

Async batch endpoints

The Async batches API can be used for processing large volumes of operations asynchronously, in order to reduce aggregate processing time and network traffic when interacting with many unique objects. For example, a user can leverage async_batches to create 1000 discounts with only 3 API requests.

As shown in the diagram below, the necessary steps to create and process a batch are:

1. Create an async_batch with the desired batch_type

2. Add tasks (individual operations) to your batch. You can add up to 1,000 tasks with each request, up to 10,000 tasks per batch.

3. Submit the batch for processing. Until a batch is submitted for processing, no tasks are attempted.

4. You may retrieve the batch to view progress details while it processes, or register for the async_batch/processed webhook to receive immediate notification of batch completion.

5. Page through the tasks in the batch to view results of each completed or failed task.

Related guides: Examples of Async batches

Endpoints
POST
/async_batches
GET
/async_batches/{id}
GET
/async_batches
POST
/async_batches/{batch_id}/process
Expand

Async batch tasks

Most commonly, the response from listing tasks on an async_batch id will be identical to the body of a singular request to standard Recharge API endpoints. However, in some instances there are variations from the standard list task response body. See below for examples corresponding to each batch_type.

Related guides: Examples of async batches

Endpoints
POST
/async_batches/{batch_id}/tasks
GET
/async_batches/{batch_id}/tasks
Expand

Token information

This resource allows a caller to inspect basic information regarding the token in use. It will only return a single object related to the calling token ( ie - a call with api_token.id=1 will only return information regarding api_token.id=1.

Endpoints
GET
/token_information
Expand