Subscriptions

Open Sky Commerce supports subscription products with recurring billing. Customers purchase a subscription plan at checkout, and renewals are charged automatically on a schedule. Customers can view and cancel their subscriptions from the My Account area.

Setting Up a Subscription Product

Go to Admin → Products → Add Product (or edit an existing product).
Set the Product Type to either Subscription Physical (recurring shipment) or Subscription Digital (recurring download or access).
Under Subscription Plans, add at least one plan. Each plan requires:
- A display name (e.g. "Monthly", "Annual")
- A billing interval (monthly, quarterly, annually, etc.)
- A price — shown as the product's price on the storefront
For Subscription Digital products, also attach a downloadable file from DigitalOcean Spaces. The customer receives a download link after each successful payment.
Save the product.

If multiple plans exist, customers choose their preferred plan on the product detail page before adding to cart.

Subscription Checkout

When a customer adds a subscription product to cart and proceeds to checkout, they are routed to the subscription checkout at /checkout/subscribe. This is a separate, streamlined checkout flow that:

Captures card details and stores the payment method for future renewals
Charges the first billing period immediately
Creates a subscription order record with status Active
Sends an order confirmation email

All four payment processors (Stripe, Authorize.net, Clover, Square) support subscription checkout. The stored payment method format differs per provider but is handled transparently by the platform.

Recurring Billing Cron Job

Subscription renewals are handled by a cron endpoint at /api/cron/billing. This endpoint:

Finds all Active subscription orders whose next billing date has passed
Charges the stored payment method off-session using the active payment processor
On success: updates the billing period dates and sends a renewal confirmation email
On failure: marks the subscription as past-due or cancelled depending on retry settings

You must configure an external cron service to call this endpoint on a regular schedule (daily is recommended). Options include:

DigitalOcean App Platform — add a job component in your app spec that runs curl https://yourstore.com/api/cron/billing on a schedule
Cron-job.org — free external cron service; point it at your billing endpoint
GitHub Actions — use a scheduled workflow to call the endpoint via curl

Secure the endpoint by verifying a shared secret in the request headers. Add a CRON_SECRET environment variable and validate it in the route handler.

Subscription Statuses

Active — Subscription is current. Renewal will be charged on the next billing date.
Paused — Billing suspended. No charges until resumed. Currently set manually by an admin.
Cancelled — Customer or admin cancelled the subscription. No further charges. The customer retains access until the end of the current billing period.
Expired — The subscription period ended without a successful renewal.

Customer-Facing Subscription Management

Customers manage their subscriptions from the My Account area:

My Account → Orders — The order list includes a filter bar with tabs for All Orders, Regular Orders, and Subscription Orders. Subscription order rows show the subscription status badge.
My Account → Subscriptions — A dedicated page showing only subscription orders with their current status, plan name, and next billing date. Customers can cancel an Active subscription from this page or from the order detail view.

Cancellation is immediate — the subscription status changes to Cancelled and no further renewals are scheduled. Customers retain access for the remainder of the paid billing period.

Admin View

Subscription orders appear in Admin → Orders alongside regular orders. The order detail view shows subscription-specific fields including billing status, period start/end dates, and the stored payment method reference (not the raw card details — just the provider's payment method identifier).

Product Types — How to set up subscription product types and plans
Payment Processors — Configuring the processor used for recurring billing
Order Management — Admin order view and subscription statuses