Core Resources

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

idinteger
Unique numeric identifier for the subscription.
address_idinteger
Unique numeric identifier for the address the subscription is associated with.
cancellation_reasonstring
Reason provided for cancellation.
cancellation_reason_commentstring
Additional comment for cancellation.
cancelled_atstring
The time the subscription was cancelled.
charge_interval_frequencystring
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_atstring
The time the subscription was created.
customer_idinteger
Unique numeric identifier for the customer the subscription is tied to.
emailstring
The email address of the customer.
expire_after_specific_number_of_chargesinteger
Set the number of charges until subscription expires.
has_queued_chargesboolean
Retrieves 1 if there is queued charge. Otherwise, retrieves 0.
is_prepaidboolean
Value is set to True if it is a prepaid item.
is_skippableboolean
Value is set to True if it is not a prepaid item
is_swappableboolean
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_reachedboolean
Retrieves 1 if charge has an error max retries reached. Otherwise, retrieves 0.
next_charge_scheduled_atstring
Date of the next charge for the subscription.
order_day_of_monthinteger
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_weekinteger
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_frequencystring
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_unitstring
The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.
priceinteger
The price of the item before discounts, taxes, or shipping have been applied.
product_titlestring
The name of the product in a shop’s catalog.
propertiesstring
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.
quantityinteger
The number of items in the subscription.
recharge_product_idinteger
Unique number identifier of the product in Recharge.
shopify_product_idinteger
Unique number identifier of the product in Shopify.
shopify_variant_idinteger
Unique number identifier of the product variant in Shopify.
skustring
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_overrideboolean
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.
statusstring
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_titlestring
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

POST/subscriptions

Scopewrite_subscriptions

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.

Body parameters

address_idintegerRequired
Unique numeric identifier of the customer’s address.
charge_interval_frequencyintegerRequired
The number of units, specified in order_interval_unit, between each charge.
customer_idstring
Unique numeric identifier of the customer.
expire_after_specific_number_of_chargesstring
The number of charges until the subscription expires.
next_charge_scheduled_atstringRequired
This will set the first charge date of a new subscription.
order_day_of_monthstring
This is populated when order_interval_unit has value “month”. Default value is 0.
order_day_of_weekstring
This is populated when order_interval_unit has value “week”.
order_interval_frequencystringRequired
The number of units, specified in order_interval_unit, between each order.
order_interval_unitstringRequired
The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.
pricestring
The price of the product.
propertiesstring
The list of line item objects.
product_titlestring
The name of the product.
quantitystringRequired
The quantity of the product
shopify_product_idstringRequired
Unique numeric identifier of the product id in Shopify.
shopify_variant_idstringRequired
Unique numeric identifier of the product variant id in Shopify.
statusstring
Default is set to "ACTIVE".
Default ACTIVE

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

GET/subscriptions/{id}

Retrieve a subscription using the Recharge subscription id.

Scoperead_subscriptions

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

PUT/subscriptions/{id}

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

Scopewrite_subscriptions

Query parameters

force_updateboolean
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_frequencystringRequired
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_updateboolean
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_chargesstring
The number of charges until subscription expires.
order_day_of_monthstring
The day of the month the order is created on.

WARNING: this update will remove skips and manually changed charges.
order_day_of_weekstring
The day of the week the order is created on.

WARNING: this update will remove skips and manually changed charges.
order_interval_frequencystringRequired
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_unitstringRequired
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.
overridestring
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.
pricestring
The price of the item before discounts, taxes, or shipping has been applied.
product_titlestring
The name of the product.
propertiesstring
List of properties.
quantitystring
The number of items in the subscription.
shopify_variant_idstring
Unique number identifier of the product variant in Shopify.
skustring
A unique identifier of the item in the fulfillment.
sku_overridestring
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_defaultsboolean
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_titlestring
The name of the product variant.

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

DELETE/subscriptions/{id}

We now have a feature for deleting a subscription.

Scopewrite_subscriptions

Body parameters

send_emailboolean
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.

DELETE/subscriptions/{id}

curl -X DELETE -H 'https://api.rechargeapps.com/subscriptions/89559201' \
 -H 'X-Recharge-Access-Token: your_api_token'

Response

{}

#List subscriptions

GET/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>

Scoperead_subscriptions

Query parameters

address_idstring
Return the subscriptions linked to the given address id.
created_at_maxstring
Return the subscriptions created before the given date.
created_at_minstring
Return the subscriptions created after the given date.
customer_idstring
Return the subscriptions linked to the given Recharge customer id.
idsstring
Comma-separated list of subscription ids to filter
include_onetimesstring
(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.
limitstring
The number of results. Default value is 50 and maximum is 250.
Default 50Maximum 250
pagestringDeprecated
The page to show. Default value is 1.
Default 1
Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
shopify_customer_idstring
Return the subscriptions linked to the given Shopify customer id.
shopify_variant_idstring
Return the subscriptions linked to the given Shopify product variant id.
statusstring
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_maxstring
Return the subscriptions updated before the given date.
updated_at_minstring
Return the subscriptions updated after the given date.

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

GET/subscriptions/count

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

Scoperead_subscriptions

Query parameters

address_idstring
Return the count of subscriptions linked to the given address id.
created_at_maxstring
Return the count of subscriptions created before the given date.
created_at_minstring
Return the count of subscriptions created after the given date.
customer_idstring
Return the count of subscriptions linked to the given customer id.
shopify_customer_idstring
Return the count of subscriptions linked to the given Shopify customer id.
shopify_variant_idstring
Return the count of subscriptions that have the provided shopify_variant_id
statusstring
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_maxstring
Return the count of subscriptions updated before the given date.
updated_at_minstring
Return the count of subscriptions updated after the given date.

Response attributes

countinteger

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

POST/subscriptions/{id}/set_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

Scopewrite_subscriptions

Body parameters

datestringRequired
The next charge date desired.

POST/subscriptions/{id}/set_next_charge_date

curl -X POST '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

POST/subscriptions/{id}/change_address

Update an existing subscription’s address.

Scopewrite_subscriptions

Body parameters

address_idstringRequired
Unique id of the address that need to be associated with subscription.
next_charge_scheduled_atstring
Date and time when next charge need to be scheduled.

POST/subscriptions/{id}/change_address

curl -X POST '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

POST/subscriptions/{id}/cancel

Cancel an active subscription.

Scopewrite_subscriptions

An involuntary subscription cancelled due to max retries reached will trigger the charge/max_retries_reached webhook.

Body parameters

cancellation_reasonstringRequired
Reason for subscription cancellation.
cancellation_reason_commentsstring
Cancellation reason comment. Maximum length is 1024 characters.
send_emailstring
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

POST/subscriptions/{id}/cancel

curl -X POST '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

POST/subscriptions/{id}/activate

Activate a cancelled subscription.

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

Scopewrite_subscriptions

POST/subscriptions/{id}/activate

curl -X POST '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

POST/addresses/{id}/subscriptions-bulk

Bulk create new subscriptions.

There is a limit of 20 subscriptions per request.

Scopewrite_subscriptions

Body parameters

charge_interval_frequencystringRequired
The number of units, specified in order_interval_unit, between each charge.
customer_idstring
Unique numeric identifier of the customer.
expire_after_specific_number_of_chargesstring
The number of charges until subscription expires.
next_charge_scheduled_atstringRequired
This will set the first charge date of a new subscription.
order_day_of_monthstring
This is populated when order_interval_unit has value “month”. Default value is 0.
order_day_of_weekstring
This is populated when order_interval_unit has value “week”.
order_interval_frequencystring
The number of units, specified in order_interval_unit, between each order.
order_interval_unitstringRequired
The frequency which a subscription should have the order created with. Valid values are “day”, “week”, and “month”.
pricestring
The price of the product.
product_titlestring
The name of the product.
propertiesstring
The list of line item objects.
quantitystringRequired
The quantity of the product.
shopify_variant_idstringRequired
Unique numeric identifier of the product variant in Shopify.
statusstring
Default is set to "ACTIVE".
Default ACTIVE

POST/addresses/{id}/subscriptions-bulk

curl -X POST '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

PUT/addresses/{id}/subscriptions-bulk

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.

Scopewrite_subscriptions

Body parameters

idstringRequired
Unique identifier of subscription.
address_idstring
Can be used to change the address of the subscriptions.
cancellation_reasonstring
Used to provide cancellation reason when cancelling subscriptions.
cancellation_reason_commentsstring
If cancellation_reason is provided, this attribute can be used to provide additional cancellation reason comments. Maximum length is 1024 characters.
charge_interval_frequencystringRequired
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_chargesstring
The number of charges until the subscription expires.
force_updateboolean
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_atstringRequired
Can be used to change the date of the next queued charge (must be current or future date).
order_day_of_monthstring
The day of the month order is created.

WARNING: this update will remove skips and manually changed charges.
order_day_of_weekstring
The day of the week order is created.

WARNING: this update will remove skips and manually changed charges.
order_interval_frequencystring
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_unitstringRequired
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.
pricestring
The price of the item before discounts, taxes, or shipping has been applied.
product_titlestring
The name of the product.
propertiesstring
List of properties.
quantitystring
The number of items in subscription.
send_emailstring
If set to false, subscription cancelled email will not be sent to customer and store owner.
shopify_variant_idstring
Unique number identifier of the product variant in Shopify.
skustring
A unique identifier of the item in the fulfillment.
sku_overridestring
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_defaultsboolean
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.
statusstring
Status of the subscription. Can be used to cancel subscriptions when set to CANCELLED or to re-activate subscriptions when set to ACTIVE.
variant_titlestring
The name of the product variant.

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,
      "quantity": 3
    },
    {
      "id": 64993718,
      "price": 24,
      "quantity": 4
    },
    {
      "id": 64993719,
      "price": 25,
      "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

DELETE/addresses/{id}/subscriptions-bulk

Bulk delete subscriptions.

There is a limit of 20 subscriptions per request.

Scopewrite_subscriptions

Body parameters

idintegerRequired
Unique identifier of subscription.
send_emailboolean
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.

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": []
}