Subscriptions

Overview

The SCAYLE Subscription Add-on empowers customers to subscribe to products for regular deliveries, automating repeat purchases and enhancing customer retention. This convenience allows customers to make regular purchases effortlessly. This Add-on is pre-installed in the Storefront Application (versions 1.0.0-rc.8 and later).

Subscription Section on the Product Detail Page

Configuration

To activate the subscription feature, several preliminary steps are required. Initially, it's essential to configure environment variables at runtime within your nuxt.config.ts's public runtime configuration. This setup involves specifying web hosts for the overview page and cancellation page, alongside a variable dedicated to the API URL for the Subscription service.

export default defineNuxtConfig({
  /* ... */
  runtimeConfig: {
    /* ... */
    public: {
      /* ... */
      subscription: {
        overviewWebHost: process.env.NUXT_PUBLIC_SUBSCRIPTION_OVERVIEW_WEB_HOST ?? '', // Override: NUXT_PUBLIC_SUBSCRIPTION_OVERVIEW_WEB_HOST
        cancellationWebHost: process.env.NUXT_PUBLIC_SUBSCRIPTION_CANCELLATION_WEB_HOST ?? '', // Override: NUXT_PUBLIC_SUBSCRIPTION_OVERVIEW_WEB_HOST
        apiUrl: process.env.NUXT_PUBLIC_SUBSCRIPTION_API_URL ?? '', // Override: NUXT_PUBLIC_SUBSCRIPTION_API_URL
      },
      /* ... */
    },
    /* ... */
  },
  
  subscription: {
    overviewPagePath: '/path/to/overview',
    cancellationPagePath: '/path/to/cancellation',
  },

  /* ... */
})

Additionally, there is an option to customize the paths for the overview and cancellation pages through the modules configuration:

Path	Type	Default
`overviewPagePath`	`string`	/account/subscription
`cancellationPagePath`	`string`	/account/subscription-cancellation

Core Components & Composables

ProductSubscription Component

The ProductSubscription component is pre-configured and ready for use. To utilize this component, you must supply the product, the currently selected variant, and the desired quantity.

<ProductSubscription
  v-if="isProductSubscriptionEligible(product)"
  :product="product"
  :variant="activeVariant"
  :quantity="quantity"
  @add-item-to-basket="addItemToBasket($event)"
/>

The isProductSubscriptionEligible function, sourced from subscription/helpers/subscription.ts, verifies the product's eligibility for subscription.

Optional Properties:

preferredDeliveryDate (PreferredDeliveryDate[]): To customize the delivery dates, you can provide an array of dates. The label utilizes an i18n-key that incorporates a variable for the day, allowing the day to be dynamically inserted (e.g., "Ever {dayOfMonth} of the month").TypeScript
```
type PreferredDeliveryDate = {
  day: number;
  label: string;
}
```
pricePromotionKey (string - Default: 'subscription'): A key used to identify the promotion associated with the subscription price.

useSubscription Composable

The useSubscription composable facilitates custom development of the Subscription component, enabling the integration of product details, pricePromotionKey, and variant information to generate all essential data for displaying subscription details.

async function useSubscription(
  product: MaybeRefOrGetter<Product>,
  pricePromotionKey: MaybeRefOrGetter<string>,
  variant: MaybeRefOrGetter<Variant | undefined>,
  quantity: MaybeRefOrGetter<number>
)

const {
  subscriptionProduct,
  subscriptionIntervals,
  subscriptionPrice,
  subscriptionVariantEligible,
  selectedVariant,
  selectedInterval,
  selectedPreferredDeliveryDate,
  itemToAdd,
  totalReductions,
  ordinalSuffixKey,
} = await useSubscription(product, pricePromotionKey, variant, quantity)

The composable returns the following reactive properties and data:

Property	Type	Description
`subscriptionProduct`	`Ref<Product> \| undefined`	Product data fetched with subscription attributes.
`subscriptionIntervals`	`ComputedRef<Value[]>`	Delivery intervals of the selected variant.
`subscriptionPrice`	`Ref<Price> \| undefined`	Price of the selected variant.
`subscriptionVariantEligible`	`ComputedRef<boolean>`	Eligibility of the variant for subscription.
`selectedVariant`	`ComputedRef<Variant \| undefined>`	Active subscription variant.
`selectedInterval`	`Ref<Value \| undefined>`	Active interval.
`selectedPreferredDeliveryDate`	`Ref<PrefferedDeliveryDate \| undefined>`	Active preferred delivery date.
`itemToAdd`	`object`	Object used for AddToBasket event, containing `variantId`, `quantity`, and `customData` for subscription definition and display data.
`totalReductions`	`ComputedRef<number>`	Percentage of the price reduction.
`ordinalSuffixKey`	`ComputedRef<Intl.LDMLPluralRule>`	Ordinal suffix for the `selectedPreferredDeliveryDate`.

itemToAdd Object Structure Example:

type ItemToAdd = {
    variantId: number;
    quantity: number;
    customData: {
        subscriptionDefinition: {
            subscriptionInterval: string;
            subscriptionDeliveryDate: number;
            subscriptionTerm: string;
            subscriptionCancellationPolicy: string;
        };
        pricePromotionKey: string;
    };
    displayData: {
        'attribute-1': {
            key: string;
            label: string;
            value: string;
        };
    };
}

Web Components (Subscription Pages)

The Subscription Add-on features two dedicated pages that are implemented as Web Components. These pages are loaded via scripts, with their web hosts configured in the Nuxt Public Runtime Config.

Overview Page

The Subscription Overview page provides a comprehensive view of a user's active subscriptions.

const { 
    isSubscriptionWebComponentLoaded, 
    isSubscriptionCancellationWebComponentLoaded,  
    apiUrl 
} = useSubscriptionWebComponent()

<subscription-overview
  v-if="isSubscriptionWebComponentLoaded"
  :base-url="apiUrl"
  :customer-token="accessToken"
  :shop-id="shopId"
/>

Cancellation Page

The Subscription Cancellation page allows users to manage or cancel their subscriptions.

<subscription-cancellation
  v-if="isSubscriptionCancellationWebComponentLoaded"
  :base-url="apiUrl"
  :shop-id="shopId"
/>

Contrary to the overview page, the cancellation page does not require the customer's access token, as it needs to be accessible without the necessity for login. Please take this into account when setting up route protection.

I18n Keys

The default subscription component requires specific i18n keys to display the correct labels.

"subscription": {
    "title": "Subscription",
    "one_time_purchase": "One-Time Purchase",
    "subscribe": "Subscribe & Save",
    "subscribe_with_reduction": "Subscribe & Save up to {percentage}%",
    "interval": "Interval",
    "choose_interval": "Choose Interval",
    "follow_up_delivery": "Follow-up delivery",
    "day_of_month_selection_caption": "Ever {dayOfMonth} of the month",
    "or": "Or save even more:",
    "select_size_message": "Select size to see options",
    "not_eligible_message": "The selected size is not eligible for a subscription",
    "term": "Term",
    "add_to_basket": "Subscribe for {interval}"
  },