Software Engineer Encyclopedia
0%
Domain 14 · SaaS & Product Engineering · Pillar

Billing وSubscriptions لـ SaaS (ومعاها اقتصاديات الـ AI)

Billing & Subscriptions

Plans وentitlements، تسعير بالـ seats وبالاستخدام، flows زي Stripe، webhooks idempotent ومش مرتبة، proration، dunning، الضرائب، invoice ledger، وهامش الربح لكل tenant واقتصاديات الـ AI — بمعمل متنفّذ.

  • Professional Engineering
  • ~13 min read
  • 19 sections
  • 8 code examples
  • 3 diagrams
  • 9 questions
  • Priority L2 · Essential
  • .NET 9 · PostgreSQL · Stripe.net (أو أي payment provider — راجع الـ API الحالي) · المعمل Python stdlib (executed)

بعد الدرس ده هتقدر

  • تفصل الـ plan عن الـ entitlements وتطبقها في الكود
  • تصمم تسعير seat-based وusage-based وhybrid وتعرف أثر كل واحد على الـ AI
  • تبني integration مع payment provider: checkout، subscriptions، customer portal
  • تعالج webhooks بشكل idempotent ومحمي من التكرار وعدم الترتيب
  • تحسب proration وتصمم dunning وتتعامل مع الضرائب بأدوات متخصصة
  • تبني invoice/usage ledger قابل للمراجعة وتحسب gross margin لكل tenant وunit economics للـ AI

المتطلبات قبل ما تبدأ

01

ليه الـ billing مشكلة هندسية صعبة

Why billing is hard engineering
Basics

الـ billing هو الجزء الوحيد في المنتج اللي أي bug فيه = فلوس غلط عند عميل حقيقي، وثقة بتتكسر بسرعة. والـ AI صعّبه: التكلفة بقت متغيرة لكل عميل (tokens)، فالـ flat pricing القديم ممكن يخليك تخسر في أكتر عملائك استخدامًا. الدرس ده بيبني الـ billing كنظام: كتالوج plans، entitlements، metering، integration مع provider، webhooks، ledger، والأرقام اللي الإدارة هتسألك عنها (الهامش لكل tenant).

Plan catalogueversioned pricesEntitlementsseats · features · quotasUsage ledgerimmutable eventsPayment providersubscriptions · invoicesreport usageWebhook handler (idempotent, order-tolerant)updates subscription state → entitlements
Billing architecture: your system owns entitlements and usage truth; the payment provider owns money movement
02

Plans مقابل Entitlements

Never branch on plan names in business code
Deep dive

الغلطة الكلاسيكية: if (tenant.Plan == "Pro") allowExport = true; متوزعة في 40 مكان. أول ما sales يبيع «Pro + SSO كاستثناء لعميل»، أو تغيّر الخطط، كل الأماكن دي بتتكسر. الصح: الـ plan (منتج تسويقي) بيتحول لـ entitlements (حقوق قابلة للقياس)، والكود بيسأل عن الحق مش عن اسم الخطة.

C#Entitlements.cs
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».

03

نماذج التسعير وأثرها على AI

Seat-based, usage-based and hybrid pricing
Deep dive
النموذجمزاياعيوب مع 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 بيسجله).

04

Integration مع payment provider (مثال Stripe)

Checkout, subscriptions and the customer portal
Practical

تقسيم المسؤولية: الـ provider بيمسك الكروت والدفع والفواتير الرسمية والضرائب (لو فعّلت) والـ retries. إنت بتمسك الكتالوج، الـ entitlements، الـ usage، وربط الـ tenant بالـ customer. ما تخزنش بيانات كروت أبدًا (PCI) — خلي الـ provider يجمعها في الـ checkout بتاعه.

C#CheckoutEndpoints.cs (Stripe.net — verify current API names in the docs)
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.

05

Webhooks: idempotent ومش مرتبة

At-least-once, out-of-order delivery done right
Deep dive

الحقائق: الـ providers بيبعتوا الـ webhooks at-least-once (ممكن تيجي مرتين)، ومش بالضرورة بالترتيب، ولو الـ endpoint بتاعك رد بخطأ بيعيدوا المحاولة لفترة. يعني الـ handler لازم: (1) يتحقق من التوقيع، (2) يتجاهل المكرر، (3) ما يطبقش حالة قديمة فوق أحدث، (4) يرد بسرعة.

C#StripeWebhookEndpoint.cs
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.

06

معمل: proration، webhooks مكررة ومش مرتبة، والهامش لكل tenant

Executed lab
Practical
Pythonbilling_lab.pyExecuted ✓
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}")
ConsoleOutput — captured from a real run
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 لنموذج أرخص للاستخدام الكثيف.
07

Dunning: لما الدفع يفشل

Failed payments, grace periods and recovery
Deep dive
  1. الـ provider بيعيد محاولة الكارت حسب جدول (smart retries).
  2. إنت بتبعت إيميلات واضحة للـ billing admin (مش لكل المستخدمين) مع رابط تحديث وسيلة الدفع (customer portal).
  3. Grace period (مثلًا 7–14 يوم): الخدمة شغالة مع banner.
  4. بعدها: Suspended (قراءة و export، من غير كتابة ولا AI) — مش حذف.
  5. بعد فترة أطول: الإلغاء وجدولة الحذف حسب الـ retention في العقد.
Failure case

Suspension اتطبق على الـ API لكن مش على الـ background jobs: الـ ingestion والـ AI summaries فضلت شغالة لـ tenant موقوف شهرين، بتكلفة حقيقية ومن غير إيراد. الـ tenant status لازم يتشيك في كل entry point: API، jobs، webhooks الخارجة، والـ agents.

08

الضرائب و invoice ledger

Tax engines and an auditable financial trail
Deep dive
  • الضرائب (VAT/GST/sales tax) بتعتمد على مكان العميل ونوعه (B2B بـ VAT ID ولا B2C) ونوع المنتج، والقواعد بتتغير. ما تكتبش محرك ضرائب بنفسك؛ استخدم خاصية الـ provider أو خدمة متخصصة، وخزّن الـ tax IDs والعنوان المعتمد. وفي بعض الدول فيه متطلبات e-invoicing خاصة (مثلًا أنظمة فوترة إلكترونية حكومية) — دي بتتحدد مع المالية/القانوني لكل سوق.
  • Invoice ledger عندك: حتى لو الـ provider بيصدر الفواتير، خزّن نسخة: رقم الفاتورة، السطور، الضرائب، العملة، الحالة، والـ usage events اللي اتبنت عليها. ده اللي بيجاوب «ليه الفاتورة دي كده؟» ويستخدم في الـ revenue reporting والـ reconciliation.
  • العملة والتقريب: decimal مش double، والتقريب في مكان واحد بقاعدة واحدة (زي money() في المعمل).
SQLinvoices.sql
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()
);
09

AI unit economics والهامش لكل tenant

Gross margin per tenant and per feature
Deep dive

Gross margin = (الإيراد − تكلفة تقديم الخدمة) ÷ الإيراد. في SaaS تقليدي تكلفة التقديم صغيرة ومستقرة؛ مع AI بتبقى بند كبير ومتغير. لازم تعرف لكل tenant ولكل feature:

SQLmargin_by_tenant.sql
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).

10

الـ subscription كـ state machine

Subscription lifecycle as a state machine
Deep dive

أغلب bugs الـ billing جاية من إن الكود بيتعامل مع الاشتراك كـ boolean «مدفوع/مش مدفوع». الحقيقة إنه state machine، وكل حالة ليها معنى مختلف للـ entitlements. الحالات تحت هي اللي Stripe بيستخدمها لـ subscription.status (راجعها في الـ docs وقت التنفيذ)، والفكرة نفسها تنطبق على أي provider.

incompletetrialingactivepast_dueunpaidcanceledpausedincomplete_expiredfirst payment oktrial ends + paidrenewal failsretry okretries exhausted~23h no payment
Subscription states and what the product grants in each (Stripe-style statuses)
الحالةالمنتج يدي إيه؟ (قرار بيزنس)UX
trialingfeatures الخطة كاملة، بحدود trialعدّاد أيام + CTA لإضافة كارت
activeكل entitlements الخطةعادي
past_dueغالبًا استمرار الخدمة أثناء فترة السماح (grace)banner «حدّث وسيلة الدفع» للـ admins بس
unpaid / canceledread-only أو downgrade لـ free؛ ما تمسحش البيانات فورًاشاشة تفعيل + export البيانات
pausedلا استخدام، البيانات محفوظةزر استئناف

المبدأ: الـ provider مصدر الحقيقة للـ payment state، وانت مصدر الحقيقة للـ entitlements. بتحوّل الأول للتاني في مكان واحد (pure function مختبرة)، مش في كل controller.

C#EntitlementPolicy.cs: one pure mapping, fully unit-tested
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
        };
}
11

Webhook processing pipeline بالتفصيل

Receiving provider events safely
Deep dive
Providerretries ~3 days/webhooks/billingverify signatureInbox tableUNIQUE(event_id)Workerre-fetch subscriptionEntitlements+ audit + email200 OK within seconds (even for duplicates)Order is NOT guaranteed: never apply event payloads blindly; reconcile with the provider's current state
Webhook intake: verify, store, ack fast; process asynchronously and idempotently; re-fetch state
C#BillingWebhook.cs (Stripe.net shown; same shape for any provider)
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 والكود.

12

Upgrade و downgrade و cancel: قواعد عملية

Changing plans without surprising anyone
Practical
العمليةالتوقيت المعتادالفلوسالـ entitlements
Upgradeفوريproration (فرق باقي الفترة) يتحصّل فورًا أو في الفاتورة الجايةترتفع فورًا بعد تأكيد الدفع
Downgradeنهاية الفترة غالبًامن غير refund جزئي (سياسة شائعة)تقل عند التجديد؛ اعرض «هيتغير في تاريخ كذا»
Cancelcancel_at_period_endمفيش تجديدكاملة لحد نهاية الفترة
Seats ±فوريproration للمقاعدممنوع تقلل تحت عدد الأعضاء الحاليين

Downgrade فوق الحد: tenant عنده 12 مستخدم وعايز ينزل لخطة 5. الخيارات: ترفض لحد ما يقلل، أو تسمح وتحوّل الزيادة read-only. اختار، واكتبه في الـ ADR، واختبره. Checkout: استخدم صفحات الـ provider المستضافة (Checkout/Customer Portal) بدل ما تجمع بيانات الكارت بنفسك — ده بيشيل عنك أغلب PCI scope.

13

Plan limits: enforcement في الـ backend

Enforcing quotas and feature flags
Deep dive
C#PlanLimits.cs: one guard used by endpoints, jobs and AI calls
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 لكل فترة/دفعة.
14

اختبار الـ billing قبل ما يلمس فلوس حقيقية

Testing billing flows
Practical
  • 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 ضاع.
15

Knowledge check

Check your understanding
Basics

وصل event customer.subscription.updated (status=active) بعد event أحدث فيه status=canceled بسبب إعادة المحاولة. الكود بيطبّق الـ payload مباشرة. النتيجة؟

فين المكان الصح لفرض حد «5 مستخدمين في الخطة Starter»؟

16

اختبر فهمك

Knowledge check
Basics

مصدر الحقيقة لحالة الاشتراك بعد الـ checkout؟

ليه الكود يسأل عن entitlement مش عن اسم الخطة؟

17

تمارين محلولة

Solved exercises
Practical
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 فالإعادات آمنة.

18

Mini project: Billing للـ capstone

Mini project
Practical

في الـ 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 برسالة واضحة.

19

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) ليه بنستخدم decimal للفلوس؟
لأن double بيمثل الكسور العشرية بشكل تقريبي (0.1 + 0.2 ≠ 0.3)، والفروق دي بتتراكم في الفواتير. decimal دقيق للكسور العشرية.
(Senior) صمّم webhook handler للـ billing.
التحقق من التوقيع، idempotency بـ unique event id في نفس الـ transaction، ack سريع ونقل الشغل لـ queue، order tolerance (version/timestamp أو re-fetch)، تحديث الـ entitlements، monitoring للفشل، و reconciliation دوري.
(Senior) إزاي تسعّر AI feature في SaaS؟
قيس التكلفة لكل وحدة قيمة من الـ ledger، اختار وحدة مفهومة للعميل، hybrid (حصة في الخطة + overage أو credits)، limits تحمي الهامش، وراجع الـ margin لكل tenant شهريًا.
(Staff) الـ AI costs بقت 40% من الإيراد. خطة 90 يوم؟
رؤية: margin لكل tenant/feature من الـ ledger. Quick wins: caching، max tokens، routing (بـ eval). تسعير: حصص و overage للعملاء الجدد، ومفاوضة للـ outliers. منصة: gateway موحد بـ budgets. متوسط المدى: distillation/self-host للحجم الكبير الثابت. ومقياس نجاح متفق عليه مع المالية.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

مصادر تعليمية ومتقدمة — Third-party & advanced reading

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس