Subscriptions

Understanding subscriptions

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 thatsubscription_id, just like customer_id are globally unique. The following table details which scopes are required to read and write the subscription record.

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

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, Recharge ensures that if a charge is processed before the regeneration resolves, it will auto-trigger the regeneration before processing. If you want to trigger the regeneration yourself, set the commit_update parameter to false.

Subscriptions FAQ

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.