Manage orders, refunds and subscriptions
You can refund an order, cancel or resume a subscription, let buyers manage their billing and re-apply a failed webhook.
After a sale, operators work in the Commerce and Security areas of the admin console, and buyers use their billing pages. Every change goes through the payment provider, so what is available depends on the active provider.
Before you begin
- A connected provider that has taken at least one payment. See Connect a payment provider.
- Permissions for what you plan to do:
orders.writefor refunds,subscriptions.writefor subscription changes,webhooks.writeto retry webhooks. The matching.readpermissions open the pages. - Refunds from the console need Stripe, WeChat Pay or Alipay; Creem and Waffo refunds are made in their own dashboards. Subscription changes and the customer portal need Stripe or Creem.
Refund an order
Open the order
Go to Commerce → Orders (/admin/orders) and open the order.
Create the refund
Enter the Amount cents to return and a Reason, then click Create refund. The refund is recorded with status pending, succeeded, failed or not configured.
A succeeded refund of the full amount revokes the licences the order issued. A partial refund revokes nothing. A refund does not change the order status or take back credits, so deduct credits by hand if needed. See Charge usage with credits. Creem refunds are made in the Creem dashboard.
Cancel or resume a subscription
Open the subscription
Go to Commerce → Subscriptions (/admin/subscriptions) and open the subscription.
Apply the change
Click Cancel at period end to stop renewal, or Resume subscription to undo it. The change is sent to the provider.
Both actions need the provider's subscription id, which arrives with the paid webhook.
Let buyers manage their billing
Buyers see their plan, orders and invoices at /app/billing, with CSV export. For cards and cancellations they use the provider's customer portal.
Open the portal page
The buyer opens /app/billing/portal.
Create a session
They leave Provider on Configured default, enter their Provider customer ID (for Stripe, cus_…) and click Create portal session. When the provider creates the session, the page shows Portal ready: followed by the portal URL. Otherwise it shows the status.
Replace the portal form
The portal page is a basic form. In your product, replace it with a button that passes the customer id you already store for the buyer.
Retry a failed webhook
A correctly signed webhook that failed to apply, for example because of a temporary database error, can be applied again.
Find the event
Go to Security → Webhooks (/admin/billing-webhooks) and open the event to see its payload, signature result and error.
Retry
Click Retry on a failed event. The stored payload is applied again and the result is recorded as a new event.
Events with an invalid signature cannot be retried. Resend them from the provider dashboard.
Verify
- After a refund, the order page lists the refund with its status, and a full refund removes the licence from the buyer's
/app/licences. - After Cancel at period end, the subscription page shows Cancel at period end as
yes. Resume subscription sets it back tono. - After a retry, Webhooks shows a new event for the same payload.
pnpm validate:billing checks the refund, subscription and webhook paths. With sandbox ids set, pnpm validate:external calls the real portal, cancel, resume and refund endpoints.
Troubleshooting
A Stripe refund fails with "no PaymentIntent to refund"
The message The Stripe checkout session has no PaymentIntent to refund. means the checkout session never produced a payment, so there is no charge to return.
Cancel or resume returns missing_provider_subscription
The paid webhook carrying the provider subscription id has not arrived yet. Check Webhooks for the event, and register the webhook if it is missing.
The refund is recorded as not configured or failed
Not configured means the credentials of the provider that took the order are missing on Payment Config. For a failed refund, Webhooks lists a refund.failed event with the error. Providers other than Stripe fail with This payment provider does not support refunds through this adapter., so refund in their dashboard.
The portal page reports that the portal is not configured
The active provider has no customer portal. Only Stripe and Creem offer one.