Subscriptions

Set up recurring billing and subscription management

Overview

Shoppex handles recurring payments automatically. Create subscription products and let us manage renewals, retries, and cancellations.

This guide is about the subscription flow itself. For Developer API endpoints and webhook event names, use the API reference and webhook docs.

Creating a Subscription Product

1. Create Product

   Go to Products → Create Product and select Subscription as the product type.

2. Configure Billing

   Set the billing interval:

   • Daily - Charged every day
   • Weekly - Charged every 7 days
   • Monthly - Charged on the same day each month
   • Yearly - Charged annually
3. Set Trial Period (Optional)

   Offer a free trial before the first charge:

   • 7-day trial
   • 14-day trial
   • 30-day trial
   • Custom duration

Handling Failed Payments

When a renewal payment fails, Shoppex:

1. Retries automatically - 3 attempts over 7 days
2. Notifies the customer - Email with payment update link
3. Marks as past_due - Subscription continues during grace period
4. Cancels - After all retries fail

Configure retry behavior in Settings → Subscriptions.

Customer Portal

Give customers control over their subscriptions via the Shoppex billing portal. Each customer receives a unique portal link in their confirmation emails where they can:

• View billing history
• Update payment method
• Cancel subscription
• Download invoices

The customer portal link is included in all subscription-related emails sent to customers.

Webhooks

Subscribe to these events for subscription updates:

Event	Description
subscription:created	New subscription started
subscription:cancelled	Subscription cancelled

Shoppex supports more subscription webhook events than the short table above, including subscription:updated, subscription:renewed, subscription:upcoming, and trial events.

See the Webhooks Guide for setup instructions.

Prorating

When customers upgrade or downgrade:

• Upgrade: Charged the difference immediately
• Downgrade: Credit applied to next invoice

Proration is calculated based on days remaining in the current billing period.

---

Headless / Developer API Checkout

Dashboard checkout and payment links already use Shoppex subscription products. For a custom frontend or backend-driven flow, start checkout with POST /dev/v1/orders, not POST /dev/v1/payments.

Endpoint	Subscription support
POST /dev/v1/orders	Yes — when items[].product_id points to a SUBSCRIPTION product
POST /dev/v1/payments	No — one-off developer invoice only; no subscription record

const response = await fetch('https://api.shoppex.io/dev/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    customer_email: '[e-mail]',
    custom_fields: { app_user_id: '154' },
    items: [{ product_id: 'YOUR_SUBSCRIPTION_PRODUCT_UNIQID', quantity: 1 }],
  }),
});

const { data } = await response.json();
// Redirect the buyer to hosted checkout, then listen for subscription:* webhooks.

After payment completes, Shoppex creates the subscription record, shows it in Dashboard → Subscriptions, and emits events such as subscription:created and subscription:renewed.

Custom fields such as plan_type: monthly do not create subscriptions by themselves. They are opaque metadata on the invoice. Recurring billing requires a real SUBSCRIPTION catalog product and the orders checkout path.

---

Managing Subscriptions via API

The Dev API exposes full subscription management. Here are the most common operations:

Action	Endpoint
List all subscriptions	GET /dev/v1/subscriptions
Get subscription details	GET /dev/v1/subscriptions/{id}
Cancel a subscription	POST /dev/v1/subscriptions/{id}/cancel
Pause billing	POST /dev/v1/subscriptions/{id}/pause
Resume billing	POST /dev/v1/subscriptions/{id}/resume
Change plan	POST /dev/v1/subscriptions/{id}/change-plan
Issue a refund	POST /dev/v1/subscriptions/{id}/refund
List available plans	GET /dev/v1/subscriptions/{id}/plan-options
Update custom fields	PATCH /dev/v1/subscriptions/{id}/custom-fields
View billing history	GET /dev/v1/subscriptions/{id}/billing-history

Listen for subscription:upcoming webhooks to send renewal reminder emails before a charge happens. This is one of the most useful subscription webhooks and often overlooked.

---

Next Steps

Webhooks Guide

Get notified about subscription lifecycle events

Invoice Guide

Understand the invoices generated by subscriptions