ليه الـ billing مشكلة هندسية صعبة
الـ billing هو الجزء الوحيد في المنتج اللي أي bug فيه = فلوس غلط عند عميل حقيقي، وثقة بتتكسر بسرعة. والـ AI صعّبه: التكلفة بقت متغيرة لكل عميل (tokens)، فالـ flat pricing القديم ممكن يخليك تخسر في أكتر عملائك استخدامًا. الدرس ده بيبني الـ billing كنظام: كتالوج plans، entitlements، metering، integration مع provider، webhooks، ledger، والأرقام اللي الإدارة هتسألك عنها (الهامش لكل tenant).
Plans مقابل Entitlements
الغلطة الكلاسيكية: if (tenant.Plan == "Pro") allowExport = true; متوزعة في 40 مكان. أول ما sales يبيع «Pro + SSO كاستثناء لعميل»، أو تغيّر الخطط، كل الأماكن دي بتتكسر. الصح: الـ plan (منتج تسويقي) بيتحول لـ entitlements (حقوق قابلة للقياس)، والكود بيسأل عن الحق مش عن اسم الخطة.
public sealed record Entitlements(
int Seats,
long MonthlyAiTokens,
int MaxDocuments,
IReadOnlySet<string> Features) // "sso", "audit_export", "byok", "agents"
{
public bool Has(string feature) => Features.Contains(feature);
}
public sealed class EntitlementService(AppDb db, IMemoryCache cache)
{
// Plan defaults + per-tenant overrides (contract exceptions) = effective entitlements, cached briefly.
public Task<Entitlements> ForAsync(Guid tenantId, CancellationToken ct) =>
cache.GetOrCreateAsync($"ent:{tenantId}", async e =>
{
e.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5);
var sub = await db.Subscriptions.AsNoTracking().SingleAsync(s => s.TenantId == tenantId, ct);
var plan = await db.PlanVersions.AsNoTracking().SingleAsync(p => p.Id == sub.PlanVersionId, ct);
var overrides = await db.EntitlementOverrides.AsNoTracking().Where(o => o.TenantId == tenantId && o.ExpiresAt > DateTimeOffset.UtcNow).ToListAsync(ct);
return plan.Apply(overrides, sub.Quantity);
})!;
}
// Usage in an endpoint:
app.MapPost("/api/audit/export", async (EntitlementService ent, ITenantContext t, CancellationToken ct) =>
(await ent.ForAsync(t.TenantId, ct)).Has("audit_export")
? Results.Accepted()
: Results.Problem(title: "Not included in your plan", statusCode: 402,
extensions: new Dictionary<string, object?> { ["upgrade"] = "/billing/plans" }));Plan versions: لما تغيّر سعر أو محتوى خطة، العملاء الحاليين غالبًا بيفضلوا على النسخة القديمة (grandfathering). عشان كده الـ subscription بتشاور على PlanVersionId مش على «Pro».
نماذج التسعير وأثرها على AI
| النموذج | مزايا | عيوب مع AI | هندسيًا محتاج |
|---|---|---|---|
| Seat-based (لكل مستخدم) | متوقع للعميل وللإيراد | مستخدم واحد ممكن يستهلك tokens بـ 10× الـ seat — هامش سالب | عدّ الـ seats، proration عند الإضافة |
| Usage-based (لكل وحدة) | الإيراد بيتبع التكلفة | فاتورة مش متوقعة = قلق العميل | metering دقيق، أسعار بالـ tiers، تنبيهات |
| Hybrid: seats + حصة AI + overage | توقع + حماية للهامش | تعقيد في الشرح | الاتنين + quotas |
| Credits (رصيد مدفوع مسبقًا) | تحكم كامل للعميل، cash مقدم | إدارة رصيد وانتهاء صلاحية | ledger للرصيد، تحويل كل استخدام لـ credits |
وحدة التسعير: العملاء ما بيفهموش «tokens». وحدات أوضح: «AI actions»، «صفحات مستندات متفهرسة»، «محادثات». جوه، كل وحدة ليها تكلفة محسوبة من الـ tokens (وده اللي الـ ledger بيسجله).
Integration مع payment provider (مثال Stripe)
تقسيم المسؤولية: الـ provider بيمسك الكروت والدفع والفواتير الرسمية والضرائب (لو فعّلت) والـ retries. إنت بتمسك الكتالوج، الـ entitlements، الـ usage، وربط الـ tenant بالـ customer. ما تخزنش بيانات كروت أبدًا (PCI) — خلي الـ provider يجمعها في الـ checkout بتاعه.
app.MapPost("/api/billing/checkout", async (CheckoutRequest req, ITenantContext t, AppDb db, IConfiguration cfg) =>
{
var tenant = await db.Tenants.SingleAsync(x => x.Id == t.TenantId);
var price = await db.PlanVersions.Where(p => p.Code == req.PlanCode && p.Active).Select(p => p.ProviderPriceId).SingleAsync();
var options = new Stripe.Checkout.SessionCreateOptions
{
Mode = "subscription",
Customer = tenant.ProviderCustomerId, // created once per tenant
LineItems = [new() { Price = price, Quantity = req.Seats }],
SuccessUrl = $"{cfg["App:BaseUrl"]}/billing/success?session={{CHECKOUT_SESSION_ID}}",
CancelUrl = $"{cfg["App:BaseUrl"]}/billing/plans",
ClientReferenceId = tenant.Id.ToString(), // ties the session back to the tenant
SubscriptionData = new() { Metadata = new() { ["tenant_id"] = tenant.Id.ToString() } },
};
var session = await new Stripe.Checkout.SessionService().CreateAsync(options,
new Stripe.RequestOptions { IdempotencyKey = $"checkout:{tenant.Id}:{req.PlanCode}:{req.Seats}:{DateTime.UtcNow:yyyyMMddHH}" });
return Results.Ok(new { url = session.Url });
}).RequireAuthorization("tenant-billing-admin");
public sealed record CheckoutRequest(string PlanCode, int Seats);مهم: نجاح الـ checkout في الـ browser (الـ SuccessUrl) مش مصدر الحقيقة — المستخدم ممكن يقفل الصفحة قبل الـ redirect. مصدر الحقيقة هو الـ webhook.
Webhooks: idempotent ومش مرتبة
الحقائق: الـ providers بيبعتوا الـ webhooks at-least-once (ممكن تيجي مرتين)، ومش بالضرورة بالترتيب، ولو الـ endpoint بتاعك رد بخطأ بيعيدوا المحاولة لفترة. يعني الـ handler لازم: (1) يتحقق من التوقيع، (2) يتجاهل المكرر، (3) ما يطبقش حالة قديمة فوق أحدث، (4) يرد بسرعة.
app.MapPost("/webhooks/stripe", async (HttpRequest req, AppDb db, IConfiguration cfg, IBackgroundQueue queue) =>
{
var json = await new StreamReader(req.Body).ReadToEndAsync();
Stripe.Event evt;
try
{
evt = Stripe.EventUtility.ConstructEvent(json, req.Headers["Stripe-Signature"], cfg["Stripe:WebhookSecret"]);
}
catch (Stripe.StripeException) { return Results.BadRequest(); } // bad signature: not from the provider
// Idempotency: a unique index on ProviderEventId makes the second insert fail -> we ack and stop.
db.ProcessedWebhooks.Add(new ProcessedWebhook(evt.Id, evt.Type, DateTimeOffset.UtcNow));
try { await db.SaveChangesAsync(); }
catch (DbUpdateException ex) when (ex.IsUniqueViolation()) { return Results.Ok(); }
await queue.EnqueueAsync(new ApplyBillingEvent(evt.Id)); // heavy work off the request path
return Results.Ok(); // ack fast to avoid provider retries
}).AllowAnonymous(); // auth = signature, not a JWT
public sealed class ApplyBillingEventHandler(AppDb db, Stripe.SubscriptionService subs, EntitlementCache ent)
{
public async Task HandleAsync(ApplyBillingEvent msg, CancellationToken ct)
{
var evt = await db.ProcessedWebhooks.SingleAsync(w => w.ProviderEventId == msg.EventId, ct);
// Order tolerance: do not trust the event payload's snapshot; fetch the CURRENT object from the provider.
var subId = evt.SubscriptionId;
var current = await subs.GetAsync(subId, cancellationToken: ct);
var local = await db.Subscriptions.SingleAsync(s => s.ProviderSubscriptionId == subId, ct);
local.Status = current.Status; // active | past_due | canceled | ...
local.CurrentPeriodEnd = current.Items.Data[0].CurrentPeriodEnd; // property location varies by API version: check docs
local.Quantity = (int)current.Items.Data[0].Quantity;
await db.SaveChangesAsync(ct);
ent.Invalidate(local.TenantId); // entitlements follow the truth
}
}بديل للـ re-fetch: قارن timestamp/version الحدث مع آخر حالة متخزنة وتجاهل الأقدم (المعمل تحت). الـ re-fetch أبسط وأصح لكن بيكلف API calls ورate limits.
معمل: proration، webhooks مكررة ومش مرتبة، والهامش لكل tenant
import random
from decimal import Decimal, ROUND_HALF_UP
from datetime import date
random.seed(12)
D = lambda x: Decimal(str(x))
money = lambda x: x.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
# ---------- 1) proration: upgrade in the middle of a monthly period ----------
def prorate(old_price, new_price, period_start, period_end, change_day):
days = (period_end - period_start).days
remaining = (period_end - change_day).days
credit = money(D(old_price) * remaining / days) # unused part of the old plan
charge = money(D(new_price) * remaining / days) # the new plan for the rest of the period
return credit, charge, money(charge - credit)
c, ch, net = prorate(49, 199, date(2026, 11, 1), date(2026, 12, 1), date(2026, 11, 17))
print(f"1) upgrade Pro(49) -> Business(199) on Nov 17: credit {c}, charge {ch}, due now {net}")
# ---------- 2) webhooks: duplicates and out-of-order delivery ----------
# The provider sends at-least-once, not in order. Events carry an id and the object's version/timestamp.
events = [
{"id": "evt_1", "type": "subscription.updated", "sub": "sub_9", "status": "active", "ts": 100},
{"id": "evt_2", "type": "invoice.payment_failed", "sub": "sub_9", "status": "past_due", "ts": 200},
{"id": "evt_3", "type": "invoice.paid", "sub": "sub_9", "status": "active", "ts": 300},
]
delivery = events + [events[1], events[0]] # duplicates
random.shuffle(delivery) # and out of order
print("2) delivery order:", [e["id"] for e in delivery])
def naive(delivery):
state = {}; emails = 0
for e in delivery:
state["sub_9"] = e["status"]
if e["type"] == "invoice.payment_failed": emails += 1
return state["sub_9"], emails
def robust(delivery):
processed, state, emails = set(), {"sub_9": {"status": None, "ts": -1}}, 0
for e in delivery:
if e["id"] in processed: continue # idempotency: an event id is handled once
processed.add(e["id"]) # (in production: unique index in the same transaction)
cur = state[e["sub"]]
if e["ts"] > cur["ts"]: # ignore stale updates (or re-fetch the object from the API)
state[e["sub"]] = {"status": e["status"], "ts": e["ts"]}
if e["type"] == "invoice.payment_failed" and e["ts"] >= state[e["sub"]]["ts"]:
emails += 1 # side effect only if still the latest truth
return state["sub_9"]["status"], emails
print(f" naive : final status={naive(delivery)[0]!r:10s} dunning emails sent={naive(delivery)[1]}")
print(f" robust: final status={robust(delivery)[0]!r:10s} dunning emails sent={robust(delivery)[1]} (truth: 'active', 0 or 1)")
# ---------- 3) gross margin per tenant from the usage ledger ----------
PLANS = {"pro": D(49), "business": D(199)}
tenants = []
for i in range(8):
plan = random.choice(["pro", "pro", "business"])
tokens_m = D(round(random.lognormvariate(0.3, 1.1), 2)) # monthly AI usage, million tokens (heavy tail)
tenants.append((f"t{i:02d}", plan, tokens_m))
COST_PER_M = D("6.00") # blended provider cost per 1M tokens (illustrative)
INFRA = D("6.00") # per-tenant infra share
print("\n3) tenant plan revenue ai_cost margin")
for t, plan, m in sorted(tenants, key=lambda x: -x[2]):
rev = PLANS[plan]; cost = money(m * COST_PER_M + INFRA); margin = (rev - cost) / rev
flag = " <-- negative margin: needs usage pricing/limits" if margin < 0 else ""
print(f" {t} {plan:9s} {rev:7} {cost:7} {margin:6.0%}{flag}")1) upgrade Pro(49) -> Business(199) on Nov 17: credit 22.87, charge 92.87, due now 70.00
2) delivery order: ['evt_1', 'evt_2', 'evt_1', 'evt_3', 'evt_2']
naive : final status='past_due' dunning emails sent=2
robust: final status='active' dunning emails sent=1 (truth: 'active', 0 or 1)
3) tenant plan revenue ai_cost margin
t05 pro 49 54.24 -11% <-- negative margin: needs usage pricing/limits
t07 pro 49 47.40 3%
t02 business 199 39.72 80%
t01 pro 49 25.98 47%
t04 pro 49 21.00 57%
t03 pro 49 19.80 60%
t00 pro 49 13.38 73%
t06 pro 49 12.84 74%- Proration: العميل دفع 49 لشهر كامل واستخدم نصه؛ الـ credit للباقي والـ charge للخطة الجديدة على الباقي. الحسبة بالأيام هنا للتوضيح؛ الـ providers بيحسبوها بالثانية غالبًا وبسياسات مختلفة (تدفع دلوقتي ولا في الفاتورة الجاية) — خليه يحسبها واعرض النتيجة (preview) للعميل قبل التأكيد.
- Webhooks: الـ handler الساذج انتهى بحالة
past_dueرغم إن الفاتورة اتدفعت، وبعت إيميلي dunning — لعميل دفع! ده بالظبط نوع الـ bug اللي بيوصل لـ CEO العميل. الـ robust تجاهل المكرر والقديم. - الهامش: نفس الخطة (Pro بـ 49) لكن tenant واحد هامشه سالب بسبب استخدام AI كبير (توزيع heavy-tail). من غير ledger بالتكلفة لكل tenant، ده ما بيبانش لحد ما الفاتورة الإجمالية للـ provider تفاجئ الكل. الحلول: حصة AI في الخطة + overage، أو limits، أو routing لنموذج أرخص للاستخدام الكثيف.
Dunning: لما الدفع يفشل
- الـ provider بيعيد محاولة الكارت حسب جدول (smart retries).
- إنت بتبعت إيميلات واضحة للـ billing admin (مش لكل المستخدمين) مع رابط تحديث وسيلة الدفع (customer portal).
- Grace period (مثلًا 7–14 يوم): الخدمة شغالة مع banner.
- بعدها:
Suspended(قراءة و export، من غير كتابة ولا AI) — مش حذف. - بعد فترة أطول: الإلغاء وجدولة الحذف حسب الـ retention في العقد.
Suspension اتطبق على الـ API لكن مش على الـ background jobs: الـ ingestion والـ AI summaries فضلت شغالة لـ tenant موقوف شهرين، بتكلفة حقيقية ومن غير إيراد. الـ tenant status لازم يتشيك في كل entry point: API، jobs، webhooks الخارجة، والـ agents.
الضرائب و invoice ledger
- الضرائب (VAT/GST/sales tax) بتعتمد على مكان العميل ونوعه (B2B بـ VAT ID ولا B2C) ونوع المنتج، والقواعد بتتغير. ما تكتبش محرك ضرائب بنفسك؛ استخدم خاصية الـ provider أو خدمة متخصصة، وخزّن الـ tax IDs والعنوان المعتمد. وفي بعض الدول فيه متطلبات e-invoicing خاصة (مثلًا أنظمة فوترة إلكترونية حكومية) — دي بتتحدد مع المالية/القانوني لكل سوق.
- Invoice ledger عندك: حتى لو الـ provider بيصدر الفواتير، خزّن نسخة: رقم الفاتورة، السطور، الضرائب، العملة، الحالة، والـ usage events اللي اتبنت عليها. ده اللي بيجاوب «ليه الفاتورة دي كده؟» ويستخدم في الـ revenue reporting والـ reconciliation.
- العملة والتقريب:
decimalمشdouble، والتقريب في مكان واحد بقاعدة واحدة (زيmoney()في المعمل).
CREATE TABLE invoices (
id uuid PRIMARY KEY,
tenant_id uuid NOT NULL,
provider_invoice_id text UNIQUE NOT NULL,
period_start date NOT NULL,
period_end date NOT NULL,
currency char(3) NOT NULL,
subtotal numeric(14,2) NOT NULL,
tax numeric(14,2) NOT NULL,
total numeric(14,2) NOT NULL,
status text NOT NULL CHECK (status IN ('draft','open','paid','void','uncollectible')),
usage_snapshot jsonb NOT NULL, -- aggregated usage the lines were computed from (+ ledger query version)
created_at timestamptz NOT NULL DEFAULT now()
);AI unit economics والهامش لكل tenant
Gross margin = (الإيراد − تكلفة تقديم الخدمة) ÷ الإيراد. في SaaS تقليدي تكلفة التقديم صغيرة ومستقرة؛ مع AI بتبقى بند كبير ومتغير. لازم تعرف لكل tenant ولكل feature:
WITH revenue AS (
SELECT tenant_id, sum(total - tax) AS revenue
FROM invoices WHERE period_start = $1 AND status = 'paid' GROUP BY tenant_id
), ai_cost AS (
SELECT tenant_id, sum(cost_usd) AS ai_cost, sum(quantity) FILTER (WHERE unit LIKE '%token%') AS tokens
FROM usage_events WHERE occurred_at >= $1 AND occurred_at < $2 GROUP BY tenant_id
)
SELECT r.tenant_id, r.revenue, COALESCE(a.ai_cost, 0) AS ai_cost,
round((r.revenue - COALESCE(a.ai_cost, 0)) / NULLIF(r.revenue, 0), 3) AS ai_gross_margin
FROM revenue r LEFT JOIN ai_cost a USING (tenant_id)
ORDER BY ai_gross_margin NULLS LAST;رافعات تحسين الهامش (بالترتيب المعتاد): caching، routing لنماذج أرخص، تقصير الـ outputs والـ contexts، limits و overage pricing، self-host للحجم الكبير الثابت. وكل رافعة بتتقاس بـ eval عشان الجودة ما تقعش (درس LLMOps).
الـ subscription كـ state machine
أغلب bugs الـ billing جاية من إن الكود بيتعامل مع الاشتراك كـ boolean «مدفوع/مش مدفوع». الحقيقة إنه state machine، وكل حالة ليها معنى مختلف للـ entitlements. الحالات تحت هي اللي Stripe بيستخدمها لـ subscription.status (راجعها في الـ docs وقت التنفيذ)، والفكرة نفسها تنطبق على أي provider.
| الحالة | المنتج يدي إيه؟ (قرار بيزنس) | UX |
|---|---|---|
| trialing | features الخطة كاملة، بحدود trial | عدّاد أيام + CTA لإضافة كارت |
| active | كل entitlements الخطة | عادي |
| past_due | غالبًا استمرار الخدمة أثناء فترة السماح (grace) | banner «حدّث وسيلة الدفع» للـ admins بس |
| unpaid / canceled | read-only أو downgrade لـ free؛ ما تمسحش البيانات فورًا | شاشة تفعيل + export البيانات |
| paused | لا استخدام، البيانات محفوظة | زر استئناف |
المبدأ: الـ provider مصدر الحقيقة للـ payment state، وانت مصدر الحقيقة للـ entitlements. بتحوّل الأول للتاني في مكان واحد (pure function مختبرة)، مش في كل controller.
public static class EntitlementPolicy
{
public static Entitlements For(Plan plan, SubscriptionStatus status, DateTimeOffset now, DateTimeOffset? pastDueSince)
=> status switch
{
SubscriptionStatus.Trialing or SubscriptionStatus.Active => plan.Entitlements,
SubscriptionStatus.PastDue when pastDueSince is { } s && now - s < TimeSpan.FromDays(7)
=> plan.Entitlements, // grace period
SubscriptionStatus.PastDue or SubscriptionStatus.Unpaid => Entitlements.ReadOnly(plan),
SubscriptionStatus.Paused => Entitlements.ReadOnly(plan),
_ => Plan.Free.Entitlements, // canceled, incomplete_expired
};
}Webhook processing pipeline بالتفصيل
app.MapPost("/webhooks/billing", async (HttpRequest req, AppDb db, IOptions<StripeOptions> opt, CancellationToken ct) =>
{
var json = await new StreamReader(req.Body).ReadToEndAsync(ct); // raw body: the signature covers exact bytes
Event evt;
try { evt = EventUtility.ConstructEvent(json, req.Headers["Stripe-Signature"], opt.Value.WebhookSecret); }
catch (StripeException) { return Results.BadRequest(); } // bad signature: reject, log, alert on spikes
db.BillingInbox.Add(new InboxEvent { EventId = evt.Id, Type = evt.Type, Payload = json, ReceivedAt = DateTimeOffset.UtcNow });
try { await db.SaveChangesAsync(ct); }
catch (DbUpdateException ex) when (ex.IsUniqueViolation()) { /* duplicate delivery: already stored */ }
return Results.Ok(); // ack fast; heavy work happens in the worker
}).AllowAnonymous().DisableAntiforgery();
// Worker (BackgroundService / Hangfire job): process each inbox row once
async Task ProcessAsync(InboxEvent e, CancellationToken ct)
{
var subId = ExtractSubscriptionId(e); // from the payload
var sub = await stripe.Subscriptions.GetAsync(subId, cancellationToken: ct); // current truth, immune to ordering
var tenant = await db.Tenants.SingleAsync(t => t.BillingCustomerId == sub.CustomerId, ct);
tenant.ApplySubscription(Map(sub.Status), PlanCatalog.ByPrice(sub.Items.Data[0].Price.Id), sub.CurrentPeriodEnd()); // version-aware
e.ProcessedAt = DateTimeOffset.UtcNow;
await db.SaveChangesAsync(ct);
}أسماء الخصائص في Stripe.net بتتغير بين الـ API versions (مثلًا مكان current period end)؛ CurrentPeriodEnd() هنا helper بتاعك يعزل التفاصيل دي. ثبّت الـ API version في الـ dashboard والكود.
Upgrade و downgrade و cancel: قواعد عملية
| العملية | التوقيت المعتاد | الفلوس | الـ entitlements |
|---|---|---|---|
| Upgrade | فوري | proration (فرق باقي الفترة) يتحصّل فورًا أو في الفاتورة الجاية | ترتفع فورًا بعد تأكيد الدفع |
| Downgrade | نهاية الفترة غالبًا | من غير refund جزئي (سياسة شائعة) | تقل عند التجديد؛ اعرض «هيتغير في تاريخ كذا» |
| Cancel | cancel_at_period_end | مفيش تجديد | كاملة لحد نهاية الفترة |
| Seats ± | فوري | proration للمقاعد | ممنوع تقلل تحت عدد الأعضاء الحاليين |
Downgrade فوق الحد: tenant عنده 12 مستخدم وعايز ينزل لخطة 5. الخيارات: ترفض لحد ما يقلل، أو تسمح وتحوّل الزيادة read-only. اختار، واكتبه في الـ ADR، واختبره. Checkout: استخدم صفحات الـ provider المستضافة (Checkout/Customer Portal) بدل ما تجمع بيانات الكارت بنفسك — ده بيشيل عنك أغلب PCI scope.
Plan limits: enforcement في الـ backend
public sealed class PlanGuard(ITenantContext t, IEntitlementStore ent, IUsageCounter usage)
{
public async Task<GuardResult> CanAsync(Feature f, CancellationToken ct)
=> (await ent.GetAsync(t.TenantId, ct)).Has(f) ? GuardResult.Ok : GuardResult.Upgrade(f);
public async Task<GuardResult> ConsumeAsync(Meter m, long amount, CancellationToken ct)
{
var e = await ent.GetAsync(t.TenantId, ct);
var limit = e.Limit(m); // e.g. Meter.AiTokens -> 2_000_000 / month
var used = await usage.IncrementAsync(t.TenantId, m, amount, ct); // atomic (Redis INCRBY or SQL UPDATE ... OUTPUT)
if (used <= limit) return GuardResult.Ok;
await usage.IncrementAsync(t.TenantId, m, -amount, ct); // roll back the reservation
return e.AllowsOverage(m) ? GuardResult.Overage : GuardResult.LimitReached(m, limit);
}
}
// endpoint usage
group.MapPost("/documents", async (UploadDoc cmd, PlanGuard guard, ...) =>
{
if (await guard.ConsumeAsync(Meter.Documents, 1, ct) is { Allowed: false } r)
return Results.Problem(title: "Plan limit reached", statusCode: 402,
extensions: new Dictionary<string, object?> { ["meter"] = r.Meter, ["limit"] = r.Limit, ["upgradeUrl"] = "/billing" });
...
});- Atomic counters مش «اقرأ العدد وبعدين قارن» (race بين طلبين متزامنين).
- 402 Payment Required أو 403 مع type واضح في Problem Details، والـ Angular يعرض شاشة upgrade بدل خطأ عام.
- الـ UI بيخفي، الـ backend بيمنع: إخفاء زرار في Angular مش enforcement.
- Usage-based: سجّل الاستخدام عندك (مصدر الحقيقة)، وابعته للـ provider دوريًا بـ idempotency key لكل فترة/دفعة.
اختبار الـ billing قبل ما يلمس فلوس حقيقية
- Test mode/sandbox للـ provider مع test cards الرسمية (نجاح، رفض، 3DS).
- Stripe CLI:
stripe listen --forward-to localhost:5000/webhooks/billingوstripe trigger invoice.payment_failedلتوليد events حقيقية محليًا. - Test clocks (simulation للوقت) عشان تختبر trial ينتهي، تجديد، dunning من غير ما تستنى شهر.
- Unit tests لـ
EntitlementPolicyلكل (status × plan × grace)، وintegration tests للـ inbox: نفس الـ event مرتين، events بترتيب معكوس، signature غلط. - Reconciliation job يومي: قارن حالة كل tenant عندك بالـ provider وسجّل الاختلافات — شبكة أمان لو webhook ضاع.
Knowledge check
وصل event customer.subscription.updated (status=active) بعد event أحدث فيه status=canceled بسبب إعادة المحاولة. الكود بيطبّق الـ payload مباشرة. النتيجة؟
فين المكان الصح لفرض حد «5 مستخدمين في الخطة Starter»؟
اختبر فهمك
مصدر الحقيقة لحالة الاشتراك بعد الـ checkout؟
ليه الكود يسأل عن entitlement مش عن اسم الخطة؟
تمارين محلولة
1: عميل نقص الـ seats من 20 لـ 12 في نص الشهر. إيه الأسئلة اللي لازم تتحسم؟
الحل: credit دلوقتي ولا الفترة الجاية؟ مين من الـ 8 مستخدمين اتشال (الـ admin يختار؛ ما تشيلش عشوائي)؟ لو أقل من الحد الأدنى للخطة؟ وهل الـ downgrade بيبدأ فورًا (يفقد وصول) ولا في التجديد (شائع ومريح للعميل)؟
2: صمّم «AI credits» لخطة Pro
الحل: كل خطة بتمنح N credits شهريًا (entitlement)، كل AI action بتخصم credits حسب نوعها (جدول تحويل versioned من التكلفة)، ledger للرصيد (منح، خصم، انتهاء، شراء إضافي) بنفس فكرة الـ usage events، enforcement بـ reserve/settle، UI بيعرض الرصيد والاستهلاك، وتنبيهات 80/100%.
3: الـ webhook endpoint كان واقع 6 ساعات. إيه اللي يحصل وإيه اللي تعمله؟
الحل: الـ provider بيعيد المحاولة لفترة (راجع سياسته)، فغالبًا الأحداث هتوصل. لكن: (1) راقب webhook failures كـ alert. (2) job دوري للـ reconciliation بيقارن حالة الاشتراكات عندك مع الـ provider ويصلح الفرق. (3) الـ handler idempotent فالإعادات آمنة.
Mini project: Billing للـ capstone
في الـ CAPSTONE/ (provider في test mode): plan catalogue بنسخ، entitlements service، checkout + customer portal، webhook endpoint بالتوقيع والـ idempotency و order tolerance، usage events من الـ LLM gateway، reconciliation job، و dashboard للـ admin بالهامش لكل tenant. معيار القبول: replay لنفس الـ webhooks 3 مرات بترتيب عشوائي ← نفس الحالة النهائية ومن غير إيميلات مكررة؛ و tenant فوق حصته بيوصله 402 برسالة واضحة.
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) ليه بنستخدم decimal للفلوس؟
(Senior) صمّم webhook handler للـ billing.
(Senior) إزاي تسعّر AI feature في SaaS؟
(Staff) الـ AI costs بقت 40% من الإيراد. خطة 90 يوم؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.