Subscriptions

What is a Subscription?

Subscriptions represent individual items a customer receives on a recurring basis. Subscriptions are the core resources of the Recharge API. A subscription record is comprised of a product added to an address.

You can update the start date when a customer will first be charged and the frequency of each charge, the date of the month when an order is created, and the product's shipping frequency using the Subscriptions resource.

A customer can only have one subscription of the same product on one address. Customers can have multiple subscriptions of the same product but only if those subscriptions are attached to a different Address.

📘

Note

In the past products needed to be attached to a ruleset to be added to subscriptions, but we are in the process of deprecating rulesets.

Updating a Subscription

If you want to change any of the following attributes, you must update all of them because they are tied to one another:

• order_interval_unit
• order_interval_frequency
• charge_interval_frequency

📘

Note

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

Request limit

When updating Subscriptions in bulk, there is a limit of 20 subscriptions per request.

Deleting a Subscription

If a user deletes a subscription via the Recharge Merchant Portal, you will still be able to retrieve it using the Subscriptions API. Deleting a Subscription via API is the only way to completely remove a subscription record from the database.

Delay a Charge regeneration

You can now delay subscription charge regenerations.

Each subscription update triggers a charge regeneration. This can be time consuming if your application is performing multiple updates in sequence. Use commit_update: false in the body of your Subscriptions PUT request to perform this action more quickly. Doing so will delay charge regeneration by 5 seconds. This allows you to run multiple calls to perform changes much faster because your application does not need to wait for every charge regeneration to complete between requests and responses.

📘

Note

For extra safety, we make sure that if a charge is processed before the regeneration resolves, we will auto-trigger the regeneration before processing.
If you want to trigger the regeneration yourself, set the commit_update parameter to false.

Subscriptions FAQ

Is the subscription_id globally unique, or can the same id be used in different stores for different subscriptions?

subscription_id, just like customer_id are globally unique.

Can a subscription be made for multiple items at a time?

No. A subscription can only be linked to one product under a customer's address.

In order to sell multiple products as one subscription you can create 1 product which represents the multiple items you want to sell in the subscription and then set up the subscription against that product.

Is it possible to pull all cancellations via the API?

Yes, you can achieve this by getting all subscriptions in a CANCELLED status

curl https://api.rechargeapps.com/subscriptions?status=CANCELLED&limit=250&page=1 
-H 'X-Recharge-Access-Token: your_api_token' 
-d limit=3 
-G

More details on querying subscription in our API Reference.

By default it will limit you to 50 objects per call, but if you specify the limit to 250 it will get you 250 objects in 1 call, then use pagination to iterate trough pages to get all the cancelled subscriptions.

Is it possible to transfer a gift subscription from the gifter to the giftee upon expiration of the gift window?

Yes, it is possible. Please reach out to support for more details on setting up this flow.

Example flow:

1. The customer pre-pays 3 months of subscription, gets a link to the claiming page, sends it as a gift and the giftee claims their subscription.
2. The giftee can then use the service for 3 months without paying (as it’s been paid by the gifter).
3. After 3 months, the giftee either starts paying the subscription themselves or gives up on the service?

Can I convert regular subscription to prepaid or vice-versa?

It’s not possible to convert the same subscription. However you can always cancel the existing subscription and create a new subscription of the type you want.

Can I provide a gift for the second subscription order to a customer?

Yes, you can just create a new subscription or one time product which will have the same address as the first subscription, and set price to 0.

You just need to create new subscription where the next_charge_scheduled_at will have the same date when the second order is going to be processed, therefore the first product and the gift can be sent together.

Can ReCharge be used to process membership fees or non-physical subscriptions?

For sure!

At this moment, we are actually designed for companies who are selling physical products since we do have a lot of mechanisms and tools developed for this purpose (for example, shipping text and configurations around the system, taxes, deliveries, etc.). This can certainly be modified and adjusted on your end (and also reworded) to better adjust to your business, and if needed we can recommend a third-party developer to assist you with this further, but we’d just like to give you a heads up so you can better understand how our system works.