Subscriptions

Recurring Subscriptions

Create subscription plans, enroll subscribers, and let Mazad handle billing cycles, retries, grace periods, and lifecycle webhooks automatically.

How subscriptions work

Mazad manages the entire subscription lifecycle so you never have to build your own billing engine.

Create a Plan

Define the price, interval, and optional trial days.

Enroll Subscribers

Attach a customer wallet to the plan.

Auto Billing

Mazad charges the wallet on each cycle date.

Manage Lifecycle

Pause, resume, or cancel at any time.

Subscription lifecycle

Each subscription moves through a series of states. Transitions happen automatically based on payment outcomes.

trialing

--trial ends-->

active

--payment fails-->

past_due

--grace expires-->

canceled

From active:

--pause-->

paused

--resume-->

active

trialingOptional trial period before first charge

activeSubscription is paid and current

past_duePayment failed, in grace period with retries

pausedTemporarily suspended by merchant or subscriber

canceledPermanently ended, no further charges

Grace period and retries

When a payment fails, the subscription enters past_due status. During the grace period, Mazad retries the charge automatically.

Retry	Timing	Webhook
1st	1 day after failure	subscription.payment_retry
2nd	3 days after failure	subscription.payment_retry
3rd	7 days after failure	subscription.payment_retry
Final	Grace period expires	subscription.canceled

Configurable grace period

Set grace_period_days when creating a plan. The default is 7 days. Set it to 0 to cancel immediately on first failure.

Quick example

Create a monthly plan and subscribe a customer in two API calls.

# 1. Create a plan
curl -X POST https://wallet.e-mazad.store/api/v1/subscriptions/plans \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "amount": 15000,
    "currency": "IQD",
    "interval": "monthly",
    "trial_days": 14,
    "grace_period_days": 7
  }'

# 2. Subscribe a customer
curl -X POST https://wallet.e-mazad.store/api/v1/subscriptions \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_abc123",
    "customer_id": "cust_xyz789"
  }'

Webhook events

Listen for these events to keep your system in sync with subscription state changes.

Event	Trigger
subscription.created	A new subscription is enrolled
subscription.trial_ending	Trial ends in 3 days
subscription.activated	First successful charge or trial ended
subscription.payment_succeeded	Recurring payment collected
subscription.payment_failed	Charge attempt failed
subscription.payment_retry	Automatic retry attempted
subscription.past_due	Entered grace period
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.canceled	Subscription permanently canceled

QR Codes Plans