Manage subscriptions - Zahlo Merchant Developer Docs

Keep subscription state in your application, but let verified billing events drive entitlement changes. Every management action should identify the customer, subscription, requested effective time, and your internal account.

Change a plan

Resolve the new price on your server and inspect the resulting amount, proration, tax, and next invoice before applying it. Use a stable idempotency key for the update.

await fetch(`${API_URL}/api/v1/subscriptions/${subscription.id}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.ZAHLO_API_KEY,
    "Idempotency-Key": `plan-change-${subscription.id}-${change.id}`,
  },
  body: JSON.stringify({ priceId: "price_demo_1001" }),
});

Pause and resume

Use the explicit pause and resume actions when access should stop temporarily. Tell the customer whether an existing period remains usable and when billing restarts. Reconcile the resulting event before changing access.

Cancel

Choose immediate cancellation or period-end cancellation and show the effective date. A repeated request must not create multiple state transitions. Keep invoices, refunds, and access decisions tied to the same subscription ID.

Recovery

When an invoice needs payment action, keep the subscription in its billing state and send the customer to checkout or the customer portal. A subsequent paid event can restore access; do not create a second subscription to recover a failed invoice.