Skip to main content

Subscriptions

Methods for handling subscriptions.

listSubscriptions v1.0.0 read subscriptions Types​

Get a paginated list of subscriptions for the customer.

import { listSubscriptions } from '@rechargeapps/storefront-client';
await listSubscriptions(session, {
  limit: 25,
  sort_by: 'id-asc',
});

getSubscription v1.0.0 read subscriptions Types​

Get a subscription.

import { getSubscription } from '@rechargeapps/storefront-client';
await getSubscription(session, 123);

createSubscription v1.0.0 write subscriptions Types​

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 Plans. The product, however, does need to have at least one Plan in order to be added to a subscription.

When creating a subscription charge_interval_frequency, order_interval_frequency, order_interval_unit or plan_id are required.

import { createSubscription } from '@rechargeapps/storefront-client';
await createSubscription(session, {
  address_id: 75875888,
  charge_interval_frequency: 30,
  next_charge_scheduled_at: '2022-10-18',
  order_interval_frequency: 1,
  order_interval_unit: 'day',
  quantity: 1,
  external_variant_id: {
    ecommerce: '31589634277439',
  },
  external_product_id: {
    ecommerce: '4378133856319',
  },
});

updateSubscription v1.0.0 write subscriptions Types​

Update a subscription.

Updating parameters like frequency, charge_interval_frequency, order_interval_frequency, order_interval_unit will cause our algorithm to automatically recalculate the next charge date (next_charge_scheduled_at).

WARNING: This update will remove skipped and manually changed charges. If you want to change the next charge date (next_charge_scheduled_at) we recommend you to update these parameters first. When updating order_interval_unit OR order_interval_frequency OR charge_interval_frequency all three parameters are required.

Note: Parameters like price, sku, sku_override, variant_title, and product_title cannot be updated via the storefront.

When updating a subscription you can pass charge_interval_frequency, order_interval_frequency, order_interval_unit or plan_id.

import { updateSubscription } from '@rechargeapps/storefront-client';
await updateSubscription(session, 123, { quantity: 2 });

updateSubscriptionChargeDate v1.0.0 write subscriptions Types​

Update a subscription charge date.

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

import { updateSubscriptionChargeDate } from '@rechargeapps/storefront-client';
await updateSubscriptionChargeDate(session, 123, '2022-10-18');

updateSubscriptionAddress v1.0.0 write subscriptions Types​

Update a subscription address.

import { updateSubscriptionAddress } from '@rechargeapps/storefront-client';
await updateSubscriptionAddress(session, 123, 456);

cancelSubscription v1.0.0 write subscriptions Types​

Cancel a 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.

import { cancelSubscription } from '@rechargeapps/storefront-client';
await cancelSubscription(session, 123, {
  cancellation_reason: 'Do not want it anymore.',
  send_email: true,
});

activateSubscription v1.0.0 write subscriptions Types​

Activate a subscription.

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

import { activateSubscription } from '@rechargeapps/storefront-client';
await activateSubscription(session, 123);

skipSubscriptionCharge v1.0.0 write orders Types​

Uses a subscription ID and date to skip a charge associated with a subscription for a given date. The given date must be an upcoming charge date in the delivery schedule where a charge hasn't yet been created. This will be dependent on Delivery schedule number of days in future shown configured in the merchant-portal -> Storefront -> Customer Portal page.

If a charge already exists for this subscription on the date then use skipCharge function to skip the existing charge.

import { skipSubscriptionCharge } from '@rechargeapps/storefront-client';
await skipSubscriptionCharge(session, 123, '2022-10-24');

skipGiftSubscriptionCharge v1.5.0 write subscriptions Types​

Gift a subscription to another person. This creates onetime products for the recipient and skips that subscription for the customer.

When the gifted onetime ships the recipient receives and email notification.

import { skipGiftSubscriptionCharge } from '@rechargeapps/storefront-client';
await skipGiftSubscriptionCharge(session, [123], {
  email: 'test@rechargeapps.com',
  address1: 'Dummy Address',
  city: 'Omaha',
  country_code: 'US',
  first_name: 'Test',
  last_name: 'Address',
  phone: '123456789',
  province: 'Nebraska',
  zip: '68144',
});

createSubscriptions v1.0.0 write subscriptions Types​

Bulk create new subscriptions. Must all be for the same address. There is a limit of 20 subscriptions per request.

allow_onetimes can be passed as an option if you want to be able to create onetimes as part of this bulk create call. When creating onetimes subscription attributes (e.g. order_interval_frequency, order_interval_unit, etc.) can be null or undefined for onetimes.

import { createSubscriptions } from '@rechargeapps/storefront-client';
const subscriptions = [];
await createSubscriptions(session, subscriptions, { allow_onetimes: true });

updateSubscriptions v1.0.0 write subscriptions Types​

Bulk update subscriptions. Must all be for the same address. There is a limit of 20 subscriptions per request. Same rules apply as a single subscription update

Note: Parameters like price, sku, sku_override, variant_title, and product_title cannot be updated via the storefront.

allow_onetimes can be passed as an option if you want to be able to update onetimes as part of this bulk update call. When updating onetimes subscription attributes (e.g. order_interval_frequency, order_interval_unit, etc.) can be null or undefined for onetimes.

import { updateSubscriptions } from '@rechargeapps/storefront-client';
const subscriptions = [];
await updateSubscriptions(session, 123, subscriptions, { allow_onetimes: true });