Subscriptions

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

Create a product

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

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

Set a trial period (optional)

Offer a free trial before the first charge:

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

What a renewal delivers

A product’s renewal_delivery (extend, new or first_only) sets what a paid renewal delivers. Each variant can override it with its own renewal_delivery; null means the variant renews like the product. Set it on POST /dev/v1/products/{id}/variants, or per variant in the variants array of PATCH /dev/v1/products/{id} (a variant sent back with its id and without the field keeps its stored value). A change applies to the next renewal of every running subscription of that variant. Only subscription products accept a value. The rules are in Subscriptions › What a renewal delivers.

Handling failed payments

Card (Stripe) and PayPal renewals are retried by the provider on its own schedule; the subscription is past_due meanwhile and keeps access. A renewal billed by invoice (crypto, balance) has the shop’s time to pay; unpaid, the subscription goes on hold (past_due with hold_ends_at, no access) or ends, as the shop set it. Paid during the hold, a new period starts on the payment day. The rules are in Subscriptions › Renewals. 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. To gate access on webhooks, listen for subscription:past_due (with its reason and the renewal to pay), subscription:recovered, subscription:paused, subscription:resumed, subscription:trial:converted and subscription:payment_failed. See Webhook events. See the Webhooks Guide for setup instructions.

Plan changes

Buyers change their plan in the customer portal, and merchants on the subscription detail page. Both flows read a quote first and confirm it by its id, so the amount shown is the amount charged. The rules are in Subscriptions › Plans and plan changes.

An upgrade or a move to a longer interval starts right away and charges the prorated difference, to the second. A downgrade or a move to a shorter interval starts at the next renewal and charges nothing.
Card subscriptions are charged through Stripe (always_invoice, pending_if_incomplete). Subscriptions billed by invoice get a change invoice that is payable for 24 hours.
While a change waits for the renewal, picking another plan replaces it: the waiting change ends, and the new one is scheduled or starts right away. Picking the current plan again is the undo.
Shoppex sends subscription:plan_change_scheduled when a change waits for the renewal, and subscription:plan_changed once the subscription is on the new plan and the payment that bills it is paid. See Webhook events.

A plan change also changes what the next renewals deliver: they follow the On each renewal setting of the new plan’s variant. A variant that a subscription, a plan change or an unpaid subscription invoice names cannot be deleted: DELETE /dev/v1/products/{id}/variants/{variantId} answers 409, and a variants replacement that leaves it out is refused. Set its visibility to on_hold to stop new sales: it stays listed and cannot be bought. private only hides it from listings, and a direct link (?variant=<id>) still sells it. POST /dev/v1/subscriptions/{id}/change-plan is unchanged: it schedules a new plan of the same product and interval for the next renewal, without proration, for Stripe subscriptions that are active or in a trial. The response’s effective_at is the date the new plan starts. Until then the merchant can cancel the scheduled change on the subscription detail page. While a change is scheduled, the endpoint answers 409 plan_change_not_allowed with reason: change_scheduled; it never replaces one.

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: '[email protected]',
    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`
What can be done now	`GET /dev/v1/subscriptions/{id}/capabilities`
Preview a cancellation	`POST /dev/v1/subscriptions/{id}/cancel/preview`
Take back a scheduled cancellation	`POST /dev/v1/subscriptions/{id}/undo-cancel`
Preview a pause	`POST /dev/v1/subscriptions/{id}/pause/preview`
Preview a plan change	`POST /dev/v1/subscriptions/{id}/change-plan/preview`
Cancel a scheduled or unpaid plan change	`POST /dev/v1/subscriptions/{id}/cancel-plan-change`
Email the renewal pay link	`POST /dev/v1/subscriptions/{id}/send-pay-link`

Capabilities

GET /dev/v1/subscriptions/{id}/capabilities answers, for each action, whether it would go through now. The buyer’s portal reads the same rules, so the API and the portal agree.

`state`	Meaning
`available`	The call should go through.
`blocked`	Refused now; `reason` says why (for example `cancel_scheduled`, `limit_reached`, `change_scheduled`, `no_open_renewal`). Something can change it.
`customer_only`	Only the buyer can do it, for example update the card.
`unsupported`	The payment rail cannot do it; `reason` is `unsupported_gateway` or `provider_billed`.

pause also carries the shop’s buyer pause policy (max_days, left_this_year); a pause made by the API does not count against it. refund goes to store credit. A capability is a check before the call, not a promise: the action still decides. When it refuses, the error is 409 with code CONFLICT and a stable subcode, usually the same as the capability’s reason.

Previews

The previews write nothing and take no Idempotency-Key. Times are unix seconds.

cancel/preview (cancel_at_period_end, default false): ends_at, access_until (null when the buyer has no access now) and drops_scheduled_pause.
pause/preview (resume_at, optional): starts_at, resume_at and access_until. The pause starts at the end of the paid period, unless the shop starts pauses right away on invoice rails.
change-plan/preview (new_plan_id): the quote change-plan would confirm. It is held for 10 minutes (expires_at); change-plan quotes again when it runs.

Actions

undo-cancel, cancel-plan-change and send-pay-link take an Idempotency-Key header like every other write. send-pay-link emails the buyer the open renewal invoice and answers its pay_url, so you can show or forward it too. cancel-plan-change takes back a change waiting for the renewal, or voids the unpaid invoice of a change waiting for its payment.

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

Start here

Agents & CLI

Products

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Elements

Integrations

Customers

Resellers

Email marketing

Tutorials

Creating a subscription product

What a renewal delivers

Handling failed payments

Customer portal

Webhooks

Plan changes

Headless / Developer API checkout

Managing subscriptions through the API

Capabilities

Previews

Actions

Webhooks

Invoices

​Creating a subscription product

​What a renewal delivers

​Handling failed payments

​Customer portal

​Webhooks

​Plan changes

​Headless / Developer API checkout

​Managing subscriptions through the API

​Capabilities

​Previews

​Actions

Webhooks

Invoices

Creating a subscription product

What a renewal delivers

Handling failed payments

Customer portal

Webhooks

Plan changes

Headless / Developer API checkout

Managing subscriptions through the API

Capabilities

Previews

Actions