Subscriptions

Overview

Subscriptions turn a set of products into orders that are generated automatically on a schedule (for example every month). The backend re-resolves fresh prices at each run, applies the subscriber discount, honors stock rules, and creates a normal PENDING / UNPAID order with an order-confirmation email. When a subscription reaches its maxOrders it expires.

In v1 subscriptions are created by the merchant (admin / MCP). A storefront self-serve subscribe flow is a follow-up, so the storefront surface is read + manage only.

List Subscriptions

Requires customer authentication. Returns the logged-in customer's subscriptions:

const { data } = await client.subscriptions.list();
// {
//   items: Subscription[]  // each: id, status, frequency, customDays,
//                          // nextOrderAt, lastOrderAt, totalOrders, maxOrders,
//                          // discountPercent, items[], orderCount, ...
// }

status is one of ACTIVE, PAUSED, CANCELLED, EXPIRED, PAYMENT_FAILED. frequency is one of WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, EVERY_6_MONTHS, YEARLY, CUSTOM_DAYS (with customDays = every N days). nextOrderAt / lastOrderAt are Unix milliseconds.

Pause / Resume / Cancel

await client.subscriptions.pause(id);   // ACTIVE -> PAUSED (no orders generated)
await client.subscriptions.resume(id);  // PAUSED -> ACTIVE (re-schedules next order)
await client.subscriptions.cancel(id);  // -> CANCELLED (permanent, no more orders)

Each returns { id, status, nextOrderAt?, updatedAt }. Ownership is enforced from the authenticated session, so a customer can only touch their own subscriptions.

React Hook

import { useSubscriptions } from '@behio/storefront-sdk/react';

const { subscriptions, isLoading, pause, resume, cancel } = useSubscriptions();

The hook lists the customer's subscriptions and exposes pause / resume / cancel mutations that refresh the list on success.