Subscriptions

Sell recurring plans and let VezmoPay bill your customers automatically. You create a product with one or more plans (a price on a cadence), then create a subscription for a customer. VezmoPay collects the first payment, saves the payment method, and charges every cycle — with automatic retries (dunning) if a charge fails. Every subscription charge settles into your VezmoPay balance just like any other sale.

Required API-key permissions

• subscription.create — create or cancel a subscription.
• subscription.read — list / retrieve subscriptions.

Both are part of the default subscription permission group, so most keys already have them — grant them under Settings → Developer Settings if yours does not.

Authentication

Calls authenticate like the rest of the API: send your key as a bearer token in the Authorization header.

Authorization: Bearer sk_live_your_api_key

Create a subscription

POST /api/v1/merchant/subscription

Provide the planId and the customer's email. If you don't pass a saved payment method, the response includes a checkoutPath — a white-label hosted checkout link. Send it to your customer; when they enter and save their card, the subscription activates and renews automatically.

curl -X POST https://api.vezmo.com/api/v1/merchant/subscription \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "<plan_id>",
    "customerEmail": "jane@example.com",
    "customerName": "Jane Doe"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "<subscription_id>",
    "subscriptionRef": "VS7K2P9Q4F",
    "status": "INCOMPLETE",
    "checkoutPath": "/checkout/subscription/<token>",
    "firstInvoiceRef": "VI3N8W5X2M"
  }
}

Build the full checkout URL as https://user.vezmo.com{checkoutPath} and send it to the customer.

List subscriptions

GET /api/v1/merchant/subscription — optional query status (e.g. active, past_due, canceled), take, skip.

Retrieve a subscription

GET /api/v1/merchant/subscription/{id} — returns the subscription with its customer, plan items, and recent invoices.

Cancel a subscription

POST /api/v1/merchant/subscription/{id}/cancel

By default the subscription cancels at the end of the current period (the customer keeps access until then). Pass { "atPeriodEnd": false } to cancel immediately.

Pause & resume

POST /api/v1/merchant/subscription/{id}/pause stops billing until you resume — the customer keeps their saved payment method and mandate. POST /api/v1/merchant/subscription/{id}/resume reactivates it and schedules the next charge.

Update a subscription

POST /api/v1/merchant/subscription/{id}/update — change the quantity (seats). Pass { "quantity": 5 }. The next invoice bills the new quantity. (Plan changes with proration aren't supported via the API yet.)

Subscription statuses

• incomplete — created, awaiting the first payment.
• trialing — in a free trial; not yet charged.
• active — good standing; renewing automatically.
• past_due — a renewal failed; retries in progress.
• unpaid — retries exhausted; access should be revoked.
• paused — billing paused.
• canceled — ended.

Webhooks

Subscribe to these events to keep your system in sync — each delivers a white-label payload with the subscriptionRef, status, plan, customer, and (where relevant) invoice:

• subscription.activated — first payment succeeded; now active.
• subscription.renewed — a renewal payment succeeded.
• subscription.payment_failed — a charge failed (a retry is scheduled, or action is needed).
• subscription.paused / subscription.resumed — billing paused / reactivated.
• subscription.updated — quantity/seats changed.
• subscription.canceled — the subscription ended.

Payloads are HMAC-signed. See the Webhooks guide for signature verification, retries, and delivery logs.