Skip to main content
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.

​
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:
1

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).
2

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”.
3

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).
4

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.

​
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:
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

1

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

Picks a cadence

A dropdown lists every cadence the merchant configured: “every 30 days”, “every 60 days”, “every 90 days”.
3

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

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.

​
What the merchant configures in Hiveku

/dashboard/commerce/settings/storefront has a Subscriptions panel (per shop). Settings: 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: 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

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-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}}”

Thank-you note on first subscription

Trigger: shopifySubscriptionStartedTrigger Action: send_email personal note from founder Action: log_crm_activity ‘note: First subscription — VIP candidate’

High-value churn alert

Trigger: shopifySubscriptionCancelledTrigger Filter: minAmountCents: 5000 (cancellation worth 50+/cycle) Action: notify slack #revenue "X subscription cancelled — call them”

​
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 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

1

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

Scaffold the storefront

Ask the AI agent: “Build me a shop with subscriptions.”
3

View the PDP

Visit your deployed /products/[handle]. The radio + cadence dropdown appears.
4

Place a test order

Pick subscribe, check out (use Shopify’s test card). The order appears in Shopify admin with a Subscription Contract attached.
5

Manage from /account/subscriptions

Sign in to your customer account. Pause or cancel — Shopify reflects the state change immediately.
6

Check workflow firing

Build a workflow with shopifySubscriptionStartedTrigger → send_email. Place another test order — the email fires.

​
What’s next

Storefront scaffolding

What gets generated end-to-end.

Reviews

First-party headless reviews — works alongside subscriptions.