Coinvex WooCommerce Subscriptions documentation

Collect WooCommerce subscription renewals in crypto through your own Coinvex. Before each renewal is due, the customer gets an email with a pay link. When they pay, the renewal order is marked paid and the subscription keeps running. If they don't pay, they get reminders, then a grace period, and then the subscription is put on hold until they pay.

Version 1.0.10 · Regular licence $39 (use in one end product) · Extended licence $99 (required when end users are charged) · 6 months of support, renewable · free updates while your licence is active. Free local installs (localhost/.test, 127.x.x.x, ::1, 0.0.0.0) plus up to 3 staging installs on staging subdomains per licence; staging doesn't count against your production domain.

Contents

1. Requirements
2. Install
3. Set up with Coinvex
4. How renewals work
5. Reminders, grace period and hold
6. Emails
7. The Crypto renewals screen
8. What your customers see
9. FAQ
10. Troubleshooting
11. Licence, updates and support
12. Privacy and outbound connections
13. For developers

Requirements

• WordPress 6.6 or newer and PHP 8.1 or newer.

• WooCommerce 8.6 or newer. HPOS (custom order tables) and the block checkout are both supported.

• Coinvex 2.1.0 or newer, plus the Coinvex for WooCommerce plugin 2.1.0 or newer. Version 2.1.0 adds the renewal hooks this add-on uses. You can download it from your Coinvex dashboard.

• One subscriptions plugin:

  • WooCommerce Subscriptions, or
  • the free Subscriptions for WooCommerce (by WP Swings).

  If both are active, WooCommerce Subscriptions is used and the Crypto renewals screen asks you to deactivate the other one.

• WP-Cron or a real server cron, so that Action Scheduler runs. WooCommerce already needs this.

Install

1. In WordPress, go to Plugins → Add New → Upload Plugin and upload coinvex-woo-subscriptions-1.0.10.zip.
2. Activate it. If something it needs is missing, a notice tells you what. Nothing is changed until everything is in place.
3. Go to WooCommerce → Crypto renewals → Licence and enter your licence key. It is in your aucip.com account under Licences.

To update, use Dashboard → Updates as you would for any plugin. Updates need an active licence.

Set up with Coinvex

1. Update Coinvex for WooCommerce to 2.1.0 or newer.
2. Go to WooCommerce → Settings → Payments → Coinvex. Check that it is enabled and that the API URL, API key, API secret and webhook secret are filled in. This add-on uses those same settings and has no keys of its own.
3. Webhook: in your Coinvex dashboard, under Stores → your store → Webhooks, the URL must be https://your-shop.example/wp-json/coinvex/v1/webhook (with Plain permalinks, use https://your-shop.example/?rest_route=/coinvex/v1/webhook). This is the same webhook the gateway already uses, so if normal crypto checkout works, renewals work too. The add-on only handles renewal invoices and leaves everything else to the gateway.
4. Subscription products: once the steps above are done, Coinvex declares subscription support by itself. It then appears as a payment method for subscription products in both the classic and block checkout.
5. Open WooCommerce → Crypto renewals. A blue "Finish setting up" notice lists anything still missing and disappears once all is well.
6. Optional: under Crypto renewals → Settings, set the reminder days, the grace period and admin alerts. The defaults are 7, 3 and 1 days before the due date, a 3-day grace period, and admin alerts on.

How renewals work

Crypto wallets can't be charged automatically, so each renewal is paid by the customer through a pay link:

1. Opening. A set number of days before the due date (your largest reminder day, 7 by default), the add-on opens a renewal. It creates a Coinvex invoice for the renewal amount and emails the customer a pay link. The link works without logging in, and it stays the same for the whole renewal.
2. Paying. The pay link sends the customer to the Coinvex checkout, where they pick the coin and pay. If the invoice has expired, the link shows a "Continue to payment" button, and a fresh invoice is created when they click it. Email security scanners that open links therefore never create invoices.
3. Paid early. If the money arrives before the due date, the renewal is marked Paid early. When your subscriptions plugin creates the renewal order on the due date, that order is marked paid straight away, with the Coinvex invoice id as the transaction id.
4. Paid on or after the due date. The renewal order created by your subscriptions plugin is marked paid as soon as the payment confirms. If the subscription was on hold, it is reactivated.
5. Part payments. If a customer sends less than the full amount, the renewal shows Part paid and the customer gets an email with what is left. If the invoice ends part-paid, a new invoice for the rest is created and emailed. You can turn that off under Settings.
6. Price changes and cancellations. If the renewal order total changes, for example after a plan switch or a coupon, an unpaid invoice is replaced with one for the new amount. If a subscription is cancelled, its open invoice is cancelled in Coinvex too.

Payments are always confirmed by asking Coinvex directly. The content of a webhook is never trusted on its own. If a webhook is lost, the add-on checks any open invoice it hasn't heard about for 30 minutes during its regular 15-minute run. Each email and status change happens once, even when several of these runs overlap.

Amounts are worked out from the invoice's own locked exchange quote, so network fees the customer pays are never counted as extra payment.

Reminders, grace period and hold

• If a renewal opens late, for example on a new subscription, only the latest reminder that applies is sent. Reminders never pile up.
• A grace period of 0 puts the subscription on hold as soon as the due date passes.
• While a subscription is on hold, the customer's pay link still works. Paying reactivates it automatically.

Emails

All emails are standard WooCommerce emails. They use your WooCommerce email design, you can preview them, and you can edit or switch off each one under WooCommerce → Settings → Emails. Templates can be overridden in your theme (yourtheme/woocommerce/emails/cvxs-renewal.php and cvxs-admin-alert.php).

To the customer:

• Crypto renewal: reminder. Sent before the due date, with the amount and the pay link.
• Crypto renewal: partial payment. Says what was received and what is left.
• Crypto renewal: overdue. Sent during the grace period.
• Crypto renewal: suspended. Sent when the subscription is put on hold.
• Crypto renewal: payment received. Sent when the renewal is fully paid.

To you (the store admin):

• Crypto renewal: overdue (admin). Sent once when a renewal passes its due date unpaid.
• Crypto renewal: put on hold (admin). Sent once when the grace period ends and a subscription is put on hold.
• Crypto renewal: invoice problem (admin). Sent once when a renewal invoice can't be opened on Coinvex and the add-on could not recover by itself (see Troubleshooting), so the customer can't pay yet.

Admin alerts go to the site admin email unless you set other recipients in each email's settings. To stop them, turn off Admin alerts under Crypto renewals → Settings, or disable the email in WooCommerce.

The Crypto renewals screen

Go to WooCommerce → Crypto renewals.

• Renewals. A list with Upcoming, Overdue, Needs attention and Paid filters, and a summary of what is due in the next 7 days, what is overdue, and what was collected in the last 30 days. Each row's actions let you:

  • copy the pay link,
  • email the pay link again,
  • replace the invoice,
  • open the details (invoices, transactions and a timeline).

  Run checks now runs the regular 15-minute check straight away.

• Activity. A log of invoices, payments, emails and status changes. It is kept for 60 days by default.

• Settings. Reminder days, grace period, overdue email interval, part payments, early payment, admin alerts, how long to keep activity, and the uninstall cleanup option.

• Licence. Activate the licence, check for updates, or release this site.

What your customers see

• Emails with a pay link and a clear summary of the amount, due date and what is left to pay.
• My Account → Subscriptions → (subscription). A Crypto renewal box shows the next renewal, a pay button, and progress on any part payment. If you allow it, there is also a Pay next renewal now button so the customer can pay early.
• Pay link pages. Pages such as "This renewal is paid", "Confirming your payment" and "Continue to payment" appear inside your theme, between its normal header and footer. They work on phones, in classic and block themes.

FAQ

Can renewals be charged automatically? No. Crypto wallets can't be charged without the customer, so each renewal is paid from a link. The reminders, the grace period and the hold handle customers who forget.

Do customers need to log in to pay? No. The pay link holds a long random code that works only for that one renewal. Logged-in customers can also pay from My Account.

Which coins can customers use? Whatever your Coinvex store accepts. The customer picks the coin on the Coinvex checkout page.

What if a customer pays too much? The renewal is marked paid. The extra stays in your Coinvex balance, and a note is added to the activity log.

What if a customer pays after the subscription was put on hold? The renewal order is marked paid and the subscription is reactivated.

Does it work with the block checkout and HPOS? Yes, with both.

Do I need WooCommerce Subscriptions? No. The free Subscriptions for WooCommerce plugin is also supported. Use one or the other, not both.

What happens if my licence expires? Nothing changes for your customers. See Licence, updates and support.

What gets deleted when I delete the plugin? By default, nothing: your renewal history stays in case you reinstall. Tick "Delete renewal history" under Settings before deleting if you want it removed. Orders and subscriptions are never deleted.

Troubleshooting

"Coinvex Woo Subscriptions is paused" notice. Something it needs is missing. The notice names it, usually Coinvex for WooCommerce older than 2.1.0 or no subscriptions plugin.

Coinvex isn't offered for subscription products at checkout. Check the "Finish setting up" notice on the Crypto renewals screen. Coinvex for WooCommerce must be 2.1.0 or newer and the gateway must be enabled with keys.

No renewals appear. Renewals appear only for subscriptions whose payment method is Coinvex, and only once they are inside the reminder window (7 days by default). Check that WP-Cron runs: WooCommerce → Status → Scheduled Actions should show cvxs_tick completing every 15 minutes. On sites with little traffic, set up a real server cron.

A renewal shows an invoice error. The Coinvex API didn't answer, or rejected the request. The message is shown in the row. Fix the cause, for example the API URL or keys, then use Replace invoice or let the customer open the pay link, which tries again. Nothing was charged.

A customer paid but the renewal still shows unpaid. Wait a few minutes. Crypto needs network confirmations, and the add-on rechecks open invoices every 15 minutes. Then check that the webhook URL in Coinvex is right (see Set up with Coinvex). Run checks now forces a recheck.

I restored a backup on the same site. Nothing to do. Every invoice request carries a key unique to the site and to that one attempt, so Coinvex never sees a reused request. If the restored site asks for a renewal invoice that Coinvex already has, the add-on recognises its own invoice (each invoice carries this install's id) and uses it instead of creating a second one. If Coinvex still refuses, the renewal shows the error, the scheduler retries with increasing gaps, and you get the "invoice problem" admin email (again only if a different problem turns up later).

I cloned the site (staging) or moved it to a new address. When the site address no longer matches the one the add-on was set up on, it treats the site as a copy: it creates a new install id and new request keys, and pauses renewals, new invoices, pay-link redirects and customer emails so a copy can never bill or email your real customers. A notice on every admin screen asks you to choose:

• This is a staging copy (keep paused): renewals stay off on this site. You can switch them on later.
• The site moved (resume renewals): renewals and emails start again on the new address.

Switching the live store to https, adding or dropping www., a trailing slash or a change in letter case is not a new address: the add-on compares addresses without those, keeps its install id and doesn't pause. When it does pause, it emails the store's admin address (Settings → General → Administration Email Address) once, and customers who open a pay link see "Crypto payment for this renewal is temporarily unavailable; the store has been notified."

The site moved (resume renewals) opens a confirm step that shows the old and the new address. Only confirm there if the store really lives at the new address now: from then on, customers are billed and emailed from this site.

A copy never takes over invoices created by another install (for example production's open invoices), even after you confirm the move. Point staging copies at a Coinvex test store, not your live one.

A copy at the same address can't be detected. If you copy the database to another server that runs under the same site address (for example to test a host migration), both copies look like the same install: both would run renewals and could reuse each other's invoices. Handle this by hand: before the copy runs cron, deactivate the add-on on it (or block its outgoing mail and Coinvex API access), and switch the old server off once the move is done.

Copies made with 1.0.3 or earlier (pre-release builds only). A copy that was cloned and re-keyed while running a build older than 1.0.4 has no "re-keyed" record, so it can still treat production's oldest invoices (created before 1.0.4, with no install id) as its own. No public release is affected; if you ran such a build, mark old copies as staging copies or delete them.

Emails aren't arriving. Check that each email is enabled under WooCommerce → Settings → Emails, and that your site can send mail (use an SMTP plugin on most hosts). Every send attempt is listed under Activity.

The settings say "Settings are locked". See the next section.

Licence, updates and support

• Regular licence ($39): use in one end product. Extended licence ($99): required when end users are charged.
• Sites: Free local installs (localhost/.test, 127.x.x.x, ::1, 0.0.0.0) plus up to 3 staging installs on staging subdomains per licence; staging doesn't count against your production domain. .local, .localhost and private network addresses (10.x, 172.16-31.x, 192.168.x) count as local too; local installs are free, unlimited and make no daily licence call. Staging means a staging hostname (staging.*, stage.*, dev.*, test.*, uat.*, preview.*, *-staging.*, *.staging.*), a managed-host preview domain (WP Engine, Kinsta, Cloudways, Flywheel, Pantheon, InstaWP) or a tunnel (ngrok, Expose, localtunnel, Cloudflare Tunnel, Serveo); any other host counts as production. Tunnel seats expire after 7 days without a verify (a licence check), so keep the daily check running on a tunnel site or activate it again later. If a site set up on a local address is later served on a public address, it is licensed for that public address at the next daily check. aucip.com counts the seats; if a 4th staging site is refused, the Licence tab shows "Staging limit reached (3/3)" with what to do.
• Updates are free while your licence is active, through the normal WordPress updates screen.
• Support lasts 6 months from purchase and can be renewed from your aucip.com account. To open a ticket, go to aucip.com → Support, and include your WordPress, WooCommerce and Coinvex versions plus a copy of the Activity tab.
• Licence check: once a day the plugin sends a signed check to aucip.com, with a random one-time request id so a replayed answer is refused. If the licence can't be confirmed, for example because it expired, was released from this site, or aucip.com couldn't be reached, a 14-day grace period starts and a notice shows a countdown. After 14 days, only the Settings tab and plugin updates lock. Renewals, reminders, pay links, payments, My Account and checkout keep working, and the Renewals and Activity tabs and Run checks now stay available. Entering a valid licence unlocks everything straight away.

Privacy and outbound connections

The plugin connects to only two places:

• Your own Coinvex (the API URL in Coinvex for WooCommerce), to create, read and cancel renewal invoices. It sends the amount, currency, subscription and order numbers, and the customer's email, which Coinvex shows on its checkout page and receipts.
• aucip.com, for the daily licence check and update checks. It sends only the licence key, plugin name and version, the site address, an install id and a random one-time request id (plus environment=staging on local and staging hosts; local installs make no daily call). The request id is new on every call and only lets the add-on check that aucip.com's signed answer belongs to that request. It never sends customer, order or subscription data.

It loads nothing from other domains. Its fonts and icons are bundled.

For developers

• Hooks:
  • cvxs_invoice_params (filter): change the invoice parameters before an invoice is created.
  • cvxs_email_sent (action): fires with the email type, the renewal and whether the send succeeded.
• Templates: templates/emails/ (copy them to yourtheme/woocommerce/emails/).
• Tests are in tests/ (included in the zip); see tests/README.md. composer.json/composer.lock (dev tools only: PHPUnit, WordPress Coding Standards) and the GitHub Actions CI (.github/workflows/ci.yml) are included too. The end-to-end scripts erase orders, so use a throwaway site. The WooCommerce Subscriptions e2e needs WP-Cron disabled (DISABLE_WP_CRON), and the Subscriptions for WooCommerce e2e needs one warm-up run on a brand-new site. To check a copy yourself, run php -l, PHPCS (WordPress Coding Standards, tests/phpcs.xml.dist) and PHPUnit (tests/phpunit.xml.dist).