جاري التحميل…
جاري التحميل…
Charge a customer the same amount every week or month. The customer pays the first cycle on Flow's checkout, the card they use is kept by the payment gateway, and every later cycle is charged from it automatically. Customers manage their own subscription — card, plan, pause, cancel, history — from a page Flow hosts.
POST /api/v1/subscriptions. The answer has checkoutUrl and status INCOMPLETE.checkoutUrl. They pay the first cycle; the card is saved with the gateway.ACTIVE. You receive subscription.activated.payment.succeeded (with subscriptionId and cycleNumber) and subscription.payment_succeeded.curl https://api.flow.minnha.sa/api/v1/subscriptions \
-H "X-Api-Key: $FLOW_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: start-cust-42-gold" \
-d '{
"itemId": "8f6c…",
"customerName": "Sara",
"customerEmail": "sara@example.com",
"customerPhone": "0551234567",
"customerCountry": "SA",
"couponCode": "WELCOME50",
"externalRef": "cust-42",
"metadata": { "plan": "gold" },
"successUrl": "https://shop.example.com/thanks",
"cancelUrl": "https://shop.example.com/pricing"
}'{
"id": "0d3e…",
"object": "subscription",
"status": "INCOMPLETE",
"amountPerCycle": 199.00,
"currency": "SAR",
"intervalUnit": "MONTH",
"intervalCount": 1,
"nextChargeAmount": 199.00,
"autoCharge": { "requested": true, "active": false, "card": null },
"checkoutUrl": "https://pay.flow.minnha.sa/pay/ivwOd…",
"sessionToken": "ivwOd…"
}| Field | Description |
|---|---|
itemId | Sell an item from your catalogue — its price, interval, term and trial are copied. Or give the terms yourself: |
amountPerCycle, currency, intervalUnit (WEEK|MONTH), intervalCount | Every N weeks or months. |
cycleCount, autoRenew | A term (e.g. 12 cycles) that expires, or renews on its own. Omit to run until cancelled. |
trialDays | Free days before the first cycle. A trial starts without a checkout. |
couponCode or discountPercent/discountAmount + discountCycles | A discount for some cycles or every cycle. |
autoCharge | Default true: keep the card and charge it. false: send each cycle as a payment link. |
collection | CHECKOUT (default) answers checkoutUrl. SEND_LINK starts now and texts/emails each cycle's link. |
customerCountry | Like a session's: which gateways the checkout offers. Without it, the mobile number and the customer's location decide. |
externalRef, metadata | Yours; returned on reads and webhooks. List by ?externalRef=. |
autoCharge: false — each cycle's payment link is sent to the customer, with reminders.| Status | Meaning |
|---|---|
INCOMPLETE | Waiting for the first payment. Withdrawn after 24 hours unpaid (configurable). |
TRIALING | In the free trial. subscription.trial_will_end is sent 3 days before it ends. |
ACTIVE | Paid up. |
PAST_DUE | A cycle is unpaid — a declined card being retried, or a link not yet paid. |
PAUSED | Nothing is generated or charged; paused time is not billed. |
EXPIRED | Its term ended. It can be renewed. |
CANCELLED | Ended by you, the customer or the past-due rule. |
| Endpoint | Description |
|---|---|
GET /api/v1/subscriptions?status=&customerEmail=&externalRef= | List |
GET /api/v1/subscriptions/{id} | With every cycle (its payment) and every event |
GET /api/v1/subscriptions/{id}/events | History — the same events as the webhooks |
POST /api/v1/subscriptions/{id}/change | { itemId | amountPerCycle, effective: NOW | NEXT_CYCLE } — an upgrade now owes the difference for the days left; a downgrade becomes credit |
POST /api/v1/subscriptions/{id}/cancel | { reason, atPeriodEnd } — now, or when the paid period ends |
POST /api/v1/subscriptions/{id}/undo-cancel | Keep one set to cancel at period end |
POST /api/v1/subscriptions/{id}/pause · /resume | Pause and resume |
POST /api/v1/subscriptions/{id}/update-card | Turn on automatic charging or replace the card — answers a checkoutUrl when a cycle is owed now |
POST /api/v1/subscriptions/{id}/stop-auto-charge | Send links instead of charging |
POST /api/v1/subscription-charges/{id} | Charge what is owed now (a retry, or a proration) |
POST /api/v1/subscriptions/{id}/renew | Next term, same terms, same card |
POST /api/v1/subscriptions/{id}/portal-link | A subscriptionUrl for your "Manage subscription" button |
GET|PUT /api/v1/subscriptions/settings | What customers may do, the retry days, the past-due action |
GET|POST /api/v1/subscription-coupons | Coupons |
POST /api/v1/plan-items/{id}/subscribe-link | The public subscribe link for an item |
portal-link gives a signed link to the customer's own page: their subscriptions, the card on file, the next payment, every past payment and what happened to the subscription. They can update the card, change plan, pause and cancel — only what you allow in the settings. A customer's cancel waits for the end of the paid period by default.
Sent to your webhook endpoints, signed like payment events (X-Minnha-Signature), retried until acknowledged.
| Event | When |
|---|---|
subscription.created | Created (any status) |
subscription.activated | The first payment arrived |
subscription.trial_will_end · subscription.trial_ended | Trial ending soon · ended |
subscription.cycle_created | A cycle is owed (data.amount, data.dueDate) |
subscription.payment_succeeded | A cycle or proration was paid |
subscription.payment_failed | The card was declined (data.reason, data.nextRetryDate) |
subscription.past_due | A cycle went unpaid |
subscription.payment_method_updated | A card was saved or replaced |
subscription.updated | Price/plan changed, cancel scheduled or undone, auto-charge turned on or off |
subscription.paused · resumed · cancelled · expired · renewed | Its life |
{
"event": "subscription.payment_failed",
"eventId": "6b1f…",
"createdAt": "2026-11-15T00:45:02Z",
"environment": "LIVE",
"actor": "SYSTEM",
"subscriptionId": "0d3e…",
"status": "PAST_DUE",
"externalRef": "cust-42",
"customer": { "name": "Sara", "email": "sara@example.com", "phone": "+966551234567", "country": "SA" },
"amountPerCycle": 199.00,
"currency": "SAR",
"nextCycleDate": "2026-12-15",
"cancelAtPeriodEnd": false,
"data": { "amount": 199.00, "reason": "Insufficient funds", "attempt": 1, "nextRetryDate": "2026-11-16" }
}const flow = new Minnha(process.env.FLOW_KEY!);
const sub = await flow.subscriptions.create(
{ itemId, customerEmail: user.email, externalRef: user.id },
{ idempotencyKey: `start-${user.id}-${itemId}` });
res.redirect(sub.checkoutUrl!);
// later
await flow.subscriptions.change(sub.id, { itemId: proItemId }); // upgrade, prorated
await flow.subscriptions.cancel(sub.id, { atPeriodEnd: true });
const { subscriptionUrl } = await flow.subscriptions.portalLink(sub.id);