Skip to main content

​
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:
EventDescription
subscription:createdNew subscription started
subscription:cancelledSubscription 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.

​
Managing Subscriptions via API

The Dev API exposes full subscription management. Here are the most common operations:
ActionEndpoint
List all subscriptionsGET /dev/v1/subscriptions
Get subscription detailsGET /dev/v1/subscriptions/{id}
Cancel a subscriptionPOST /dev/v1/subscriptions/{id}/cancel
Pause billingPOST /dev/v1/subscriptions/{id}/pause
Resume billingPOST /dev/v1/subscriptions/{id}/resume
Change planPOST /dev/v1/subscriptions/{id}/change-plan
Issue a refundPOST /dev/v1/subscriptions/{id}/refund
List available plansGET /dev/v1/subscriptions/{id}/plan-options
Update custom fieldsPATCH /dev/v1/subscriptions/{id}/custom-fields
View billing historyGET /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