Subscriptions

Set up recurring billing and subscription management

Shoppex handles recurring payments automatically. Create subscription products, and Shoppex manages 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 a 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 a 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 follows four steps:

1. Retries automatically — 3 attempts over 7 days
2. Notifies the customer — sends an email with a payment update link
3. Marks as past_due — the subscription continues during the grace period
4. Cancels — after all retries fail

Configure retry behavior in Settings → Subscriptions.

Customer portal

Give customers control over their subscriptions through 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: Shoppex charges the difference immediately
• Downgrade: Shoppex applies a credit to the next invoice

Shoppex calculates proration based on the 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 sends events such as subscription:created and subscription:renewed.

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

---

Managing subscriptions through the 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.

---

Webhooks

Get notified about subscription lifecycle events

Invoices

Understand the invoices generated by subscriptions