> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hiveku Subscriptions

> Subscribe-and-save on a headless Next.js storefront. Built on top of Shopify's first-party Subscription Contracts API — Shopify owns the billing engine, Hiveku ships the storefront UI.

<Note>
  This page is about **Shopify subscriptions** — recurring purchases for shoppers (e.g. "monthly coffee bag"). For the unrelated CRM/B2B billing module that handles agency invoicing and retainers, see [Commerce → Subscriptions](/commerce/subscriptions).
</Note>

## What this is

A headless storefront UI for **recurring product purchases** (subscribe-and-save). The shopper picks "every 30 days" on a product page, checks out once, and Shopify charges their card on the cadence — automatically, until they cancel.

Hiveku ships the storefront pieces that headless agencies normally hand-build for \$5–15k per merchant:

* Subscribe-vs-one-time picker on PDPs
* Cadence dropdown ("every 30 days", "every 60 days", etc.)
* Cart line subscription badges
* Customer self-service at `/account/subscriptions` (pause / resume / cancel)
* Workflow triggers for subscription events

## The split (important)

We do not build a billing engine. **Shopify owns recurring billing entirely:**

* **Shopify Payments** stores the customer's payment method (PCI handled).
* **The Shopify Subscriptions app** (free, first-party) charges the card on cadence.
* **Shopify** retries failed charges per the merchant's dunning policy.
* **Shopify** stores the Subscription Contract that ties shopper + product + cadence + price together.

Hiveku owns the storefront UI on top of that engine. We render fresh from Shopify's Customer Account API on each render — no contract mirroring, no sync layer, no drift.

This is intentional. Building our own billing engine would mean PCI compliance, dunning, retries, payment-method updates, tax compliance — six months of work to be safe, duplicating what Shopify Payments already does well.

## Hard preconditions

Before subscriptions render anything on your storefront:

<Steps>
  <Step title="Shopify Payments turned on">
    Required for the first-party Subscription Contracts API. Gates \~12 countries: US, CA, UK, AU, IE, NL, NZ, ES, IT, DE, FR + a few more. Outside those, you'll need a third-party app (ReCharge integration is a roadmap item).
  </Step>

  <Step title="Shopify Subscriptions app installed">
    Free, first-party. Provides the billing engine. Without it, `product.sellingPlanGroups` is empty everywhere and the storefront picker renders nothing.

    Install at: Shopify admin → Apps → search "Shopify Subscriptions".
  </Step>

  <Step title="Selling Plans configured on products">
    Hiveku doesn't define selling plans — it just renders what's there. Configure them in Shopify admin under your product's pricing options ("Add subscription option" → set discount + interval).
  </Step>

  <Step title="Customer Account API application registered">
    The customer-account scaffold handles the storefront side. The merchant has to register the Customer Account application in Shopify admin first so the OAuth callback works. See [Customer Account API setup](https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api).
  </Step>
</Steps>

## What gets scaffolded

The variant-picker subscribe block ships **automatically** as part of the standard `shopify_scaffold_product-detail-route`. It self-renders nothing when products have no selling plans — so on a shop with subscriptions disabled, the PDP looks unchanged.

For customer self-service (the `/account/subscriptions` pages), call `shopify_scaffold_subscriptions`:

```
app/account/subscriptions/
├── page.tsx                        # list of customer's contracts
└── [id]/page.tsx                   # detail + manage actions

app/api/subscriptions/
└── [id]/[action]/route.ts          # proxy to Customer Account API mutations

src/components/cart/
└── SubscriptionActions.tsx         # pause / resume / cancel buttons (client island)
```

Bundles `customer-account` if not already scaffolded — the subs pages read `sca_at` cookies set by the Customer Account OAuth callback.

## What the shopper experiences

<Steps>
  <Step title="Picks subscribe vs one-time on the product page">
    Two radio buttons appear above the variant options. The "Subscribe & save" radio shows a savings badge ("Save 10%") computed from the Selling Plan's pricing policy.
  </Step>

  <Step title="Picks a cadence">
    A dropdown lists every cadence the merchant configured: "every 30 days", "every 60 days", "every 90 days".
  </Step>

  <Step title="Adds to cart, checks out">
    Cart line shows a "Subscribe — every 30 days" badge so they don't lose track. Checkout is Shopify-hosted, same as one-time. Shopify creates the Subscription Contract on order completion.
  </Step>

  <Step title="Manages from /account/subscriptions">
    Lists every active and past contract. Click a contract → detail page with line items, next billing date, status. Pause / resume / cancel inline.
  </Step>
</Steps>

## What the merchant configures in Hiveku

`/dashboard/commerce/settings/storefront` has a Subscriptions panel (per shop). Settings:

| Setting               | What it does                                          | Default                 |
| --------------------- | ----------------------------------------------------- | ----------------------- |
| Master toggle         | Renders nothing storefront-wide when off              | On                      |
| Picker heading        | The label above the radios                            | "Purchase options"      |
| One-time label        | The first radio's text                                | "One-time purchase"     |
| Subscribe label       | The second radio's text                               | "Subscribe & save"      |
| Default selection     | Which radio is preselected                            | One-time                |
| Default selling plan  | Which cadence is preselected when subscribe is picked | First plan in the group |
| Savings badge         | Override the auto-computed "Save X%"                  | Auto from plan          |
| Customer self-service | Enable `/account/subscriptions` page                  | On                      |

Changes apply on the next deploy (settings flow as `NEXT_PUBLIC_SHOPIFY_SUBS_*` env vars).

## Workflow triggers

Shopify subscription events fan out into the workflow builder. Five trigger node types fire on incoming webhooks:

| Trigger node                                 | Fires on                                      |
| -------------------------------------------- | --------------------------------------------- |
| `shopifySubscriptionStartedTrigger`          | New contract created (after order completion) |
| `shopifySubscriptionPausedTrigger`           | Customer pauses                               |
| `shopifySubscriptionCancelledTrigger`        | Customer cancels (terminal)                   |
| `shopifySubscriptionBillingFailedTrigger`    | A scheduled charge fails                      |
| `shopifySubscriptionBillingSucceededTrigger` | A scheduled charge succeeds                   |

A bare `shopifySubscriptionTrigger` node matches all event types.

### Filter conditions on each node

* `eventTypes` — explicit list of event types to fire on
* `connectionId` — only fire for one specific shop
* `minAmountCents` / `maxAmountCents` — gate by charge amount

### Example automations

<CardGroup cols={2}>
  <Card title="Win-back email after cancel">
    Trigger: `shopifySubscriptionCancelledTrigger`
    Action: send\_email "We're sorry to see you go — here's 20% off your next order"
    Wait: 7 days
    Action: send\_email "Last call: same 20% offer expires tomorrow"
  </Card>

  <Card title="Card-update reminder when billing fails">
    Trigger: `shopifySubscriptionBillingFailedTrigger`
    Action: send\_email with link to update payment method in customer account
    Action: notify slack #ops "Subscription failed billing for `{{customer.email}}`"
  </Card>

  <Card title="Thank-you note on first subscription">
    Trigger: `shopifySubscriptionStartedTrigger`
    Action: send\_email personal note from founder
    Action: log\_crm\_activity 'note: First subscription — VIP candidate'
  </Card>

  <Card title="High-value churn alert">
    Trigger: `shopifySubscriptionCancelledTrigger`
    Filter: `minAmountCents: 5000` (cancellation worth $50+/cycle)
            Action: notify slack #revenue "$X subscription cancelled — call them"
  </Card>
</CardGroup>

## Inbox alerts

Failed billing seeds an item in the Hiveku ops inbox at `/dashboard/commerce/inbox` with severity `urgent`:

> **Subscription billing failed for [jane@example.com](mailto:jane@example.com)**
> A recurring charge failed on contract `gid://shopify/SubscriptionContract/...`. Shopify will retry per the merchant's dunning policy, but it's worth reaching out — failed billing is the #1 churn signal.

The CTA links straight to the merchant's Shopify Subscriptions admin page.

## What we did not ship (Phase 2)

* **Skip next billing cycle** — Customer Account API supports it; UI not wired yet.
* **Change shipping address** on an active contract — Customer Account API supports it; UI not wired yet.
* **Swap product** on an active contract — Customer Account API supports it; UI not wired yet.
* **Hiveku-managed subscription analytics** (MRR, churn, LTV) — currently merchants use Shopify's reports.
* **ReCharge integration** for non-Shopify-Payments merchants.

## How to test it end-to-end

<Steps>
  <Step title="Connect Shopify, install Subscriptions app, configure a Selling Plan">
    On a dev store. Add a "subscribe every 30 days, 10% off" plan to one product.
  </Step>

  <Step title="Scaffold the storefront">
    Ask the AI agent: "Build me a shop with subscriptions."
  </Step>

  <Step title="View the PDP">
    Visit your deployed `/products/[handle]`. The radio + cadence dropdown appears.
  </Step>

  <Step title="Place a test order">
    Pick subscribe, check out (use Shopify's test card). The order appears in Shopify admin with a Subscription Contract attached.
  </Step>

  <Step title="Manage from /account/subscriptions">
    Sign in to your customer account. Pause or cancel — Shopify reflects the state change immediately.
  </Step>

  <Step title="Check workflow firing">
    Build a workflow with `shopifySubscriptionStartedTrigger` → `send_email`. Place another test order — the email fires.
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="Storefront scaffolding" icon="hammer" href="/integrations/shopify/storefront">
    What gets generated end-to-end.
  </Card>

  <Card title="Reviews" icon="star" href="/integrations/shopify/reviews">
    First-party headless reviews — works alongside subscriptions.
  </Card>
</CardGroup>