DEV Community: Arshan Nawaz

React Native - Google Play Billing (Subscriptions) Complete Guide

Arshan Nawaz — Sun, 19 Jul 2026 12:18:29 +0000

Naming: Google Pay vs Google Play Billing

Term	What it is	When you use it
Google Play Billing	In-app purchases & subscriptions sold inside an Android app via Google Play	Digital goods, Premium tiers, unlockable features (required by Google for most digital content)
Google Pay	Wallet / card wallet for one-time payments (often via Stripe / PaymentRequest)	Physical goods, services, web checkout — not the same as Play subscriptions
Google payments profile	Merchant / tax / payout setup inside Play Console	Required before you can sell anything on Play — often mislabeled “Google Pay”

This guide covers Google Play Billing (store subscriptions). If you need a Google Pay button for one-time charges, see Appendix A.

Architecture overview
Prerequisites checklist
Play Console setup
RevenueCat dashboard setup
Product ID conventions (Android)
Install client dependency
Environment variables
Server: public config endpoint
Server: sync + webhook
Client: types
Client: RevenueCat service layer
Client: device store lock
Client: ownership alerts
Client: purchase hook (full flow)
Client: restore purchases
Client: change plan (monthly ↔ yearly)
Client: trial eligibility
Client: identify user on login / logout
Client: manage / cancel subscription
UI / UX rules
End-to-end purchase sequence
Error handling matrix
Testing (license testers)
Production gotchas
iOS parallel (optional)
File layout template
Copy-paste checklists
Appendix A — Google Pay (Wallet) vs this guide
Appendix B — Glossary

1. Architecture overview

┌─────────────┐     purchaseProduct      ┌──────────────────┐
│  React Native│ ───────────────────────► │ Google Play      │
│  + RevenueCat│ ◄─────────────────────── │ Billing Library  │
│  SDK         │     CustomerInfo         └────────┬─────────┘
└──────┬───────┘                                   │
       │ POST /billing/sync                        │ receipt
       ▼                                           ▼
┌─────────────┐     webhook (HMAC)        ┌──────────────────┐
│ Your API    │ ◄──────────────────────── │ RevenueCat       │
│ (source of  │     REST validation       │ cloud            │
│  truth for  │ ────────────────────────► └──────────────────┘
│  entitlements)│
└─────────────┘

Rules of thumb

Play owns money. Your app never stores card numbers.
RevenueCat validates receipts and sends webhooks.
Your backend is source of truth for “is this app user Premium?” after sync/webhook.
Client SDK is trusted for UI (show/hide paywall) but not for authorizing sensitive APIs alone — always check server entitlement for gated actions.

2. Prerequisites checklist

[ ] Google Play Developer account (one-time fee)
[ ] App created in Play Console with package name (e.g. com.example.myapp)
[ ] Payments profile verified (tax + merchant) — can take 2–5 business days
[ ] Bank account + tax forms for payouts (before first real earnings)
[ ] RevenueCat account + project
[ ] Backend that can expose HTTPS webhook URL
[ ] Expo / RN app that ships as Play-installed build for real Billing tests (sideload often fails Billing)

3. Play Console setup

3.1 Payments profile

Play Console → Settings → Payments profile
Create / verify merchant profile (country, individual or organization)
Complete tax info (e.g. W-8BEN for non-US) before first US sale
Add bank account for payouts
Confirm Order management is accessible

3.2 License testers (free test purchases)

Play Console → Settings → License testing
Add Gmail accounts that will test
Those accounts must also be opted into your Internal testing track later

3.3 Create subscriptions

Monetize → Subscriptions → Create subscription
Create one subscription product per cadence you sell, e.g.:
- Product: premium_monthly with base plan monthly
- Product: premium_yearly with base plan yearly
For each base plan: price, billing period, free trial / intro offer
Activate products (draft products are invisible to testers)

3.4 App signing

Production purchases require Play App Signing enabled before real money flows.

4. RevenueCat dashboard setup

Create a project (one project for sandbox + production is fine; purchases are tagged sandbox vs production)
Add Android app with the same package name as Play (com.example.myapp)
Upload Play service account JSON so RevenueCat can validate receipts
Products → Import from Google Play
Create an entitlement e.g. premium
Attach monthly + yearly products to that entitlement
Create an offering (e.g. default) with packages if you use offerings UI
Copy keys:
- Android public SDK key (goog_…)
- iOS public key if needed (appl_…)
- Secret API key for server (sk_…)
Configure webhook → your POST https://api.example.com/v1/billing/revenuecat/webhook with HMAC secret

5. Product ID conventions (Android)

Google Play uses subscriptionId:basePlanId when talking to Billing / RevenueCat:

Plan	Example product ID
Monthly	`premium_monthly:monthly`
Yearly	`premium_yearly:yearly`

Keep these IDs identical across:

Play Console
RevenueCat products
Server env / /billing/config
Client purchase calls

Never hard-code product IDs only in the app — serve them from the backend so you can rotate without shipping a binary.

6. Install client dependency

npx expo install react-native-purchases
# or
npm install react-native-purchases

Typical version family: react-native-purchases 10.x.

No separate “Google Pay” native module is required. Play Billing permission / Billing Library is pulled in by the Purchases SDK at native build time.

Expo: use a dev client / EAS build, not Expo Go, for real purchases.

7. Environment variables

Server (recommended)

# Webhook HMAC from RevenueCat dashboard
REVENUECAT_WEBHOOK_HMAC_SECRET=whsec_replace_me

# Server-side REST
REVENUECAT_SECRET_API_KEY=sk_replace_me
REVENUECAT_PROJECT_ID=projreplace_me

# Public SDK keys (safe to return to clients)
REVENUECAT_PUBLIC_IOS_API_KEY=appl_replace_me
REVENUECAT_PUBLIC_ANDROID_API_KEY=goog_replace_me

# Catalog
REVENUECAT_ENTITLEMENT_ID=premium
REVENUECAT_OFFERING_ID=default
REVENUECAT_PRO_MONTHLY_PRODUCT_ID=premium_monthly:monthly
REVENUECAT_PRO_YEARLY_PRODUCT_ID=premium_yearly:yearly

Client

Prefer no hard-coded RevenueCat keys in the app binary. Fetch from:

GET /billing/config (public / skip-auth is OK for public keys only).

8. Server: public config endpoint

Expose everything the client needs to configure the SDK and show prices:

GET /v1/billing/config

Example JSON response:

{
  "revenueCat": {
    "iosApiKey": "appl_…",
    "androidApiKey": "goog_…",
    "entitlementId": "premium",
    "offeringId": "default"
  },
  "plans": {
    "free": {
      "tier": "free",
      "label": "Free",
      "priceLabel": "$0",
      "features": {},
      "limits": {}
    },
    "pro": {
      "tier": "pro",
      "label": "Premium",
      "entitlementId": "premium",
      "monthly": {
        "priceLabel": "$4.99/mo",
        "cadence": "monthly",
        "productId": "premium_monthly:monthly"
      },
      "yearly": {
        "priceLabel": "$39.99/yr",
        "cadence": "yearly",
        "productId": "premium_yearly:yearly"
      },
      "features": {},
      "limits": {}
    }
  }
}

9. Server: sync + webhook

9.1 Client sync (fast path after purchase)

POST /v1/billing/sync
Authorization: Bearer <user JWT>

Body:

{
  "appUserId": "<same id used in Purchases.logIn>",
  "entitlement": "premium",
  "productId": "premium_monthly:monthly",
  "store": "play_store",
  "currentPeriodEnd": "2026-08-19T00:00:00.000Z"
}

Server responsibilities:

Verify the caller is authenticated
Prefer verifying against RevenueCat REST / CustomerInfo for that appUserId
Upsert subscription row for this user
If receipt already linked to another user → return 409 with clear message
Invalidate any session/bootstrap cache for that user

9.2 Webhook (source of truth for renewals / cancels)

POST /v1/billing/revenuecat/webhook

Verify X-RevenueCat-Webhook-Signature (HMAC over raw body)
Idempotent: store event IDs so retries are safe
Handle at least: INITIAL_PURCHASE, RENEWAL, PRODUCT_CHANGE, CANCELLATION, EXPIRATION, BILLING_ISSUE, UNCANCELLATION
Only grant access when the configured entitlement is present/active
Invalidate session caches after each processed event

10. Client: types

export type BillingConfigResponse = {
  revenueCat: {
    iosApiKey: string | null;
    androidApiKey: string | null;
    entitlementId: string;
    offeringId: string;
  };
  plans: {
    free: { /* … */ };
    pro: {
      entitlementId: string;
      monthly: { priceLabel: string; cadence: string; productId?: string };
      yearly: { priceLabel: string; cadence: string; productId?: string };
      // …
    };
  };
};

export type BillingSyncPayload = {
  appUserId: string;
  entitlement: string;
  productId?: string | null;
  store?: string | null;
  currentPeriodEnd?: string | null;
};

export type BillingPurchaseResult = {
  productId: string | null;
  store: string | null;
  currentPeriodEnd: string | null;
  isActive: boolean;
  willRenew: boolean | null;
};

11. Client: RevenueCat service layer

Create a single module (e.g. src/features/billing/services/purchases.ts) that owns:

Concern	Function
Configure once	`ensureConfigured(config)` → `Purchases.configure({ apiKey })`
Identify user	`logIn(appUserId)` / `logOut()`
Purchase	`purchaseProduct(productId)`
Change plan (Android)	`purchaseSubscriptionOption` + proration
Restore	`restorePurchases()`
Local entitlement	`getCustomerInfo()` → `entitlements.active[id]`
Manage UI	`showManageSubscriptions()`
Trial eligibility	platform-specific (see §17)
Errors	map RC codes → typed errors

11.1 Custom errors

export class PurchaseUnavailableError extends Error {} // cancel / missing key
export class PaymentPendingError extends Error {}      // family approval
export class AlreadyPurchasedError extends Error {}    // store already owns sub

11.2 Map purchase errors

import { PURCHASES_ERROR_CODE } from 'react-native-purchases';

function rethrowPurchaseError(err: unknown): never {
  const code = (err as { code?: PURCHASES_ERROR_CODE }).code;
  if (code === PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR) {
    throw new PurchaseUnavailableError('Purchase cancelled.');
  }
  if (code === PURCHASES_ERROR_CODE.PAYMENT_PENDING_ERROR) {
    throw new PaymentPendingError('Payment pending.');
  }
  if (
    code === PURCHASES_ERROR_CODE.PRODUCT_ALREADY_PURCHASED_ERROR ||
    code === PURCHASES_ERROR_CODE.RECEIPT_ALREADY_IN_USE_ERROR ||
    code === PURCHASES_ERROR_CODE.RECEIPT_IN_USE_BY_OTHER_SUBSCRIBER_ERROR
  ) {
    throw new AlreadyPurchasedError('Subscription already owned on this store account.');
  }
  throw err;
}

11.3 Configure + identify

import Purchases, { LOG_LEVEL } from 'react-native-purchases';
import { Platform } from 'react-native';

let sdkConfigured = false;
let loggedInAppUserId: string | null = null;

function platformApiKey(config: BillingConfigResponse): string | null {
  if (Platform.OS === 'ios') return config.revenueCat.iosApiKey;
  if (Platform.OS === 'android') return config.revenueCat.androidApiKey;
  return null;
}

export async function ensureConfigured(config: BillingConfigResponse): Promise<void> {
  if (sdkConfigured) return;
  if (await Purchases.isConfigured().catch(() => false)) {
    sdkConfigured = true;
    return;
  }
  const apiKey = platformApiKey(config);
  if (!apiKey) throw new PurchaseUnavailableError('API key missing for this platform.');
  Purchases.setLogLevel(__DEV__ ? LOG_LEVEL.DEBUG : LOG_LEVEL.INFO);
  Purchases.configure({ apiKey });
  sdkConfigured = true;
}

export async function logInPurchases(appUserId: string): Promise<void> {
  if (!appUserId || loggedInAppUserId === appUserId) return;
  await Purchases.logIn(appUserId);
  loggedInAppUserId = appUserId;
}

export async function logOutPurchases(): Promise<void> {
  try {
    if (sdkConfigured && loggedInAppUserId) await Purchases.logOut();
  } catch {
    // logOut on anonymous user can throw — ignore
  }
  loggedInAppUserId = null;
}

export async function configurePurchases(config: BillingConfigResponse, appUserId: string) {
  await ensureConfigured(config);
  await logInPurchases(appUserId);
}

Important: configure with API key once per process. Switch users with logIn, not by re-calling configure with a new identity.

11.4 Purchase

export async function purchaseProProduct(
  productId: string,
  entitlementId = 'premium',
): Promise<BillingPurchaseResult> {
  try {
    const { customerInfo, productIdentifier } = await Purchases.purchaseProduct(productId);
    return mapPurchaseResult(productIdentifier, customerInfo, productId, entitlementId);
  } catch (err) {
    rethrowPurchaseError(err);
  }
}

11.5 Connectivity probe (optional but useful)

Before opening the store sheet:

export async function checkConnection(): Promise<boolean> {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 2000);
    const res = await fetch('https://clients3.google.com/generate_204', {
      method: 'HEAD',
      signal: controller.signal,
    });
    clearTimeout(timeoutId);
    return res.status === 204;
  } catch {
    return false;
  }
}

12. Client: device store lock

Problem: Monthly and yearly are separate Play products. With RevenueCat “Keep with original App User ID”, a second app login on the same Google account can sometimes buy the other SKU while the receipt stays on the first user.

Mitigation: Persist a short-lived device lock in AsyncStorage after any successful Premium detection:

type StorePremiumLock = {
  productIds: string[];
  expiresAt: string; // ISO
  updatedAt: string;
};

Write lock after purchase / restore / active entitlement
Before purchase: if lock active OR CustomerInfo already owns configured SKUs → block with “Already subscribed on Google Play”
Auto-clear when expiresAt passes

13. Client: ownership alerts

Provide two alerts:

Already subscribed on Google Play — store account owns Premium linked to another app login
Subscription on another account — server returned 409 on sync

Both should offer a button that opens:

https://play.google.com/store/account/subscriptions

(iOS parallel: https://apps.apple.com/account/subscriptions)

Detect store ownership errors via RevenueCat codes listed in §11.2.

14. Client: purchase hook (full flow)

Recommended order inside purchase(plan):

Guard: already Premium on server → navigate to Manage, do not open sheet
Guard: purchase already in progress → return
Network check → alert if offline
Resolve productId from /billing/config for monthly/yearly
configurePurchases(config, userId)
Restore first (soft-fail unless AlreadyPurchased)
Read local entitlement — if active, sync + go Manage (skip sheet)
Store lock / CustomerInfo owns SKU → ownership alert
Stop spinner (store UI owns the wait), call purchaseProProduct
On success → POST /billing/sync
Sync 409 → cross-account alert
Sync fails but local entitlement active → toast “Premium is confirming…” → Manage
Success → Welcome / upgrade-success screen

Spinner UX

Show spinner for app-owned work only
While Play sheet is open: keep CTA disabled, hide spinner so it does not spin behind the modal

Pseudo-code outline

async function purchase(plan: 'monthly' | 'yearly') {
  if (alreadyPro) return navigateManage();
  if (busy) return;

  if (!(await checkConnection())) return alertOffline();

  const productId = plan === 'yearly' ? yearlyId : monthlyId;
  await configurePurchases(config, userId);

  // restore → local entitlement → store lock checks…
  // then:
  setSpinner(false);
  const result = await purchaseProProduct(productId, entitlementId);
  await syncBilling({
    appUserId: userId,
    entitlement: entitlementId,
    productId: result.productId,
    store: 'play_store',
    currentPeriodEnd: result.currentPeriodEnd,
  });
  navigateUpgradeSuccess();
}

15. Client: restore purchases

const info = await Purchases.restorePurchases();
// map entitlement → sync payload → POST /billing/sync

UI cases:

Result	UX
Entitlement active	Sync → Manage or success
Nothing found	“No purchases found”
Store unreachable	“Restore failed — check connection”
Sync 409	Cross-account alert

16. Client: change plan (monthly ↔ yearly)

Android (required)

Google Play’s manage-subscriptions UI cannot switch base plans. You must run an in-app replacement purchase:

import { PRORATION_MODE, PRODUCT_CATEGORY } from 'react-native-purchases';

// upgrade monthly → yearly
prorationMode = PRORATION_MODE.IMMEDIATE_WITH_TIME_PRORATION;

// downgrade yearly → monthly
prorationMode = PRORATION_MODE.DEFERRED;

const products = await Purchases.getProducts([newProductId], PRODUCT_CATEGORY.SUBSCRIPTION);
const option = products[0]?.defaultOption ?? products[0]?.subscriptionOptions?.[0];

await Purchases.purchaseSubscriptionOption(option, {
  oldProductIdentifier: oldProductId,
  prorationMode,
});

Fallback if no subscription option: purchaseStoreProduct(product, { oldProductIdentifier, prorationMode }).

iOS

Products in the same subscription group → purchaseProduct(newProductId) and StoreKit handles replacement.

17. Client: trial eligibility

Never promise “Start free trial” unless you know the store account is eligible.

Platform	How
iOS	`Purchases.checkTrialOrIntroductoryPriceEligibility(ids)`
Android	`getProducts` — if any option has `freePhase`, user is eligible (Play only returns eligible offers)

If status is unknown, treat as ineligible for CTA copy (safer).

18. Client: identify user on login / logout

Event	Action
Session bootstrap / login	`configure` + `logIn(userId)` early
Logout	`logOut()`
Purchase / restore / manage	Call configure+logIn as a safe prelude

Use your stable backend user id as RevenueCat appUserId so webhooks and sync line up.

19. Client: manage / cancel subscription

Prefer Purchases.showManageSubscriptions()
Fallback deep link: Play subscriptions URL
Tell users clearly: cancel / payment method changes happen in Google Play, not inside your app settings alone

20. UI / UX rules

Trust badge copy: “Billed through Google Play” (not “Google Pay”)
One primary CTA on paywall plan screen
Disable CTA while purchase pending
User cancel → silent return (no error toast)
Family / pending payment → dedicated “Approval Request Sent” alert
After purchase, unlock Premium only after sync or show confirming state if local entitlement is already true

21. End-to-end purchase sequence

sequenceDiagram
  participant User
  participant App
  participant RC as RevenueCat SDK
  participant Play as Google Play Billing
  participant API as Your Backend
  participant WH as RevenueCat Webhook

  User->>App: Tap Subscribe
  App->>App: Guards + restore + lock checks
  App->>RC: purchaseProduct(sku)
  RC->>Play: Present billing sheet
  User->>Play: Confirm
  Play-->>RC: Receipt
  RC-->>App: CustomerInfo (entitlement active)
  App->>API: POST /billing/sync
  WH-->>API: INITIAL_PURCHASE (async)
  API-->>App: Plan = premium
  App->>User: Upgrade success

22. Error handling matrix

Situation	User sees	App does
User cancels sheet	Nothing	Silent return
Offline	Connection alert	Abort
Already Premium (server)	—	Open Manage
Already owned on Play	Already subscribed alert	Abort / restore path
Sync 409	Another account alert	Abort
Payment pending	Approval request alert	Abort
Generic purchase failure	Purchase failed alert	Abort
Sync fails, local entitlement OK	Toast “confirming…”	Open Manage
SKU not found / not activated	Purchase failed	Check Play + RC product mapping

23. Testing (license testers)

Setup

License tester Gmail on device
Opt into Internal testing track
Install from Play opt-in link (not random sideload)
Force-stop Play Store → clear cache → reopen (stale catalog)

Happy path

Open paywall → Subscribe
Sheet shows (Test) label
Complete purchase
RevenueCat Customer view shows entitlement
App unlocks Premium
Restore after reinstall works
Cancel in Play → webhook → entitlement drops on refresh

Accelerated renewals

License tester renewals are accelerated (e.g. ~5 minutes ≈ 1 month). Use this to test renewal webhooks — not real calendar months.

First SKU delay

Brand-new products can fail for 2–6 hours while Play propagates. Retry later.

24. Production gotchas

[ ] Payments profile + tax + bank before real payouts
[ ] Play App Signing on
[ ] Products Active in Play Console
[ ] Service account JSON uploaded to RevenueCat
[ ] Webhook HMAC verified; raw body not re-serialized
[ ] Public keys served from /config, not committed secrets
[ ] Never run real (non–license-tester) purchases from a debug build against production SKUs
[ ] Monthly↔yearly change uses Android replacement purchase, not manage sheet
[ ] 409 handling for shared Google accounts / multi-login
[ ] Device store lock for Keep-with-original edge cases
[ ] usesCleartextTraffic: false and HTTPS API in production builds

25. iOS parallel (optional)

Same architecture; differences:

Topic	Android	iOS
API key	`goog_…`	`appl_…`
Store string	`play_store`	`app_store`
Product IDs	`sub:basePlan`	App Store product id
Plan change	Proration / replacement	Same subscription group
Trial API	`freePhase` on options	Intro eligibility API
Manage URL	Play subscriptions	App Store subscriptions

26. File layout template

src/
  features/
    billing/
      api/
        billing.api.ts          # getConfig, getMe, sync
      hooks/
        useBillingQueries.ts    # React Query wrappers
      lib/
        storePremiumLock.ts     # device lock
        premiumLifecycle.ts     # map plan → UI state
      services/
        purchases.ts            # RevenueCat wrapper
    monetization/
      hooks/
        useProPurchase.ts
        useProRestore.ts
        useChangePremiumPlan.ts
        usePaywallTrialEligibility.ts
      lib/
        storeOwnershipAlerts.ts
        paywall.ts
      screens/
        PaywallScreen.tsx
        PlanComparisonScreen.tsx
        ChangePlanScreen.tsx
        UpgradeSuccessScreen.tsx
server/
  modules/billing/
    billing.route.js
    revenuecat.controller.js
    revenuecat.service.js
    revenuecat.schema.js
    subscription.model.js

27. Copy-paste checklists

New project — day 1

[ ] Play app + package name locked
[ ] Start payments profile verification
[ ] Create RevenueCat project + Android app
[ ] Add react-native-purchases
[ ] Add /billing/config, /billing/sync, webhook routes

Before first test purchase

[ ] Subscriptions created + activated
[ ] Products imported + entitlement mapped in RC
[ ] Service account connected
[ ] License testers added
[ ] Internal track build installed from Play

Before production

[ ] Tax + payout methods
[ ] Webhook live + HMAC
[ ] E2E: buy, restore, cancel, renew (accelerated)
[ ] 409 / already-owned UX verified
[ ] Plan change (upgrade + downgrade) verified on Android

Appendix A — Google Pay (Wallet) vs this guide

Use this guide when selling digital Premium inside an Android app.

Use Google Pay (Wallet) when:

Charging for physical goods / services
Integrating Stripe / Braintree / etc. with a Google Pay button
Not selling a Play-managed subscription

Typical Google Pay stack (out of scope here):

@stripe/stripe-react-native → GooglePay / Payment Sheet
Or native PaymentsClient / Wallet API with gateway tokenization

Do not mix the two for the same digital entitlement — Google’s policies generally require Play Billing for digital in-app unlocks.

Appendix B — Glossary

Term	Meaning
SKU / product ID	Store catalog identifier
Base plan	Android billing period + price under a subscription
Entitlement	Logical access flag in RevenueCat (e.g. `premium`)
Offering	Packaged set of products shown to a user cohort
App User ID	Your user id passed to `Purchases.logIn`
CustomerInfo	RC snapshot of entitlements + subscriptions
Proration	How Play charges when switching plans mid-cycle
License tester	Gmail that gets free “(Test)” purchases
Keep with original	RC transfer behavior when the same store receipt hits a new App User ID

Quick reference — minimum viable integration

Play subscriptions + payments profile
RevenueCat products → entitlement premium
npm i react-native-purchases
GET /billing/config → public keys + product IDs
configure + logIn(userId)
purchaseProduct(id) → POST /billing/sync
Webhook for renewals / expiration
Restore + manage deep link
License-tester E2E before launch

Paddle Billing Integration — Implementation Guide

Arshan Nawaz — Mon, 09 Feb 2026 01:30:47 +0000

This document lists every endpoint, includes complete code for Paddle-related backend and frontend, and describes flows, edge cases, and configuration. Use it as the single reference for all Paddle work.

All endpoints
Environment and configuration
Backend — Paddle service (full code)
Backend — Discount service (full code)
Backend — Subscription routes, schema, controller (code)
Backend — Webhook (full code)
Backend — Discount routes, controller, model (code)
Backend — Models and config
Frontend — Subscription API (full code)
Frontend — Subscription page (key code)
Edge cases and checklist

1. All endpoints

Every Paddle-related endpoint. Base URL is your API root (e.g. https://api.example.com). Auth = cookie/session unless noted.

Method	Path	Auth	Description
GET	`/api/subscription/plans`	Yes	List plans (free, pro, plus, agency) with prices and features
GET	`/api/subscription/current`	Yes	Current subscription + `active_discount`; optional `?channelId=` for billing context
GET	`/api/subscription/usage`	Yes	Usage and limits for billing period; optional `?channelId=`
POST	`/api/subscription/upgrade`	Yes	Body: `{ plan, interval }`. Returns `checkoutUrl` or in-place result
POST	`/api/subscription/cancel`	Yes	Cancel subscription (owner only)
GET	`/api/subscription/billing`	Yes	List recent transactions for current user
POST	`/api/subscription/billing-portal`	Yes	Returns `{ url }` for Paddle customer portal
POST	`/api/subscription/resume`	Yes	Resume subscription scheduled to cancel (owner only)
POST	`/api/webhooks/paddle`	No (signature)	Paddle webhook; body must be raw for signature verification
GET	`/api/discounts/analytics`	Yes (admin)	Discount conversion analytics by trigger

Route mounting (server):

Subscription: apiRouter.use("/subscription", subscriptionRouter) → paths above under /api/subscription/*
Webhooks: apiRouter.use("/webhooks", webhookRouter) + webhookRouter.post("/paddle", ...) → POST /api/webhooks/paddle
Webhook raw body: app.use("/api/webhooks/paddle", express.raw({ type: "application/json" })) must be registered before app.use("/api", apiRouter) so the webhook receives raw body for signature verification.
Discounts: apiRouter.use("/discounts", discountRouter) → /api/discounts/analytics

2. Environment and configuration

Required:

PADDLE_API_KEY — API key (sandbox or production)
PADDLE_ENVIRONMENT — sandbox or production
PADDLE_WEBHOOK_SECRET — Webhook signature verification

Price IDs (all same environment as API key):

PADDLE_PRICE_PRO, PADDLE_PRICE_PRO_YEARLY
PADDLE_PRICE_PLUS, PADDLE_PRICE_PLUS_YEARLY
PADDLE_PRICE_AGENCY
Optional trial: PADDLE_PRICE_PRO_TRIAL, PADDLE_PRICE_PRO_YEARLY_TRIAL, PADDLE_PRICE_PLUS_TRIAL, PADDLE_PRICE_PLUS_YEARLY_TRIAL

Discount (optional):

DISCOUNT_SYSTEM_ENABLED — default enabled if not "false"
DISCOUNT_PERCENT_OFF_USAGE_LIMIT, DISCOUNT_PERCENT_OFF_LOCKED_FEATURE, DISCOUNT_PERCENT_OFF_ABANDONED, DISCOUNT_PERCENT_OFF_INACTIVITY
DISCOUNT_VALIDITY_DAYS, DISCOUNT_COOLDOWN_DAYS

App:

FRONTEND_BASE_URL (or WEB_APP_URL / FRONTEND_URL) — used for checkout success/cancel URLs and billing portal return URL.

3. Backend — Paddle service (full code)

File: server/src/services/paddle.js

import crypto from "crypto";
import { config } from "../config/env.js";

const SANDBOX_BASE_URL = "https://sandbox-api.paddle.com";
const PROD_BASE_URL = "https://api.paddle.com";
const PROD_PORTAL_HOST = "https://customer-portal.paddle.com";
const SANDBOX_PORTAL_HOST = "https://sandbox-customer-portal.paddle.com";

function getPaddleBaseUrl() {
  const env = (config.paddle?.environment || "production").toLowerCase();
  return env === "sandbox" ? SANDBOX_BASE_URL : PROD_BASE_URL;
}

function isPaddleSandbox() {
  return (config.paddle?.environment || "production").toLowerCase() === "sandbox";
}

function rewritePortalUrlsForEnv(obj) {
  if (!obj || !isPaddleSandbox()) return obj;
  const out = Array.isArray(obj)
    ? obj.map((item) => rewritePortalUrlsForEnv(item))
    : typeof obj === "string"
      ? obj.replace(new RegExp(escapeRegex(PROD_PORTAL_HOST), "g"), SANDBOX_PORTAL_HOST)
      : { ...obj };
  if (!Array.isArray(obj) && typeof obj === "object" && obj !== null) {
    for (const key of Object.keys(obj)) {
      out[key] = rewritePortalUrlsForEnv(obj[key]);
    }
  }
  return out;
}

function escapeRegex(s) {
  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

function requirePaddleApiKey() {
  if (!config.paddle?.apiKey) {
    throw new Error("PADDLE_API_KEY is not configured");
  }
  return config.paddle.apiKey;
}

async function paddleRequest(path, { method = "GET", body } = {}) {
  const apiKey = requirePaddleApiKey();
  const baseUrl = getPaddleBaseUrl();
  const url = `${baseUrl}${path}`;
  const res = await fetch(url, {
    method,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: body ? JSON.stringify(body) : undefined
  });

  const payload = await res.json().catch(() => ({}));
  if (!res.ok) {
    const message = payload?.error?.message || payload?.message || "Paddle API request failed";
    const err = new Error(message);
    err.status = res.status;
    err.payload = payload;
    throw err;
  }

  return payload?.data ?? payload;
}

async function createPaddleCustomer({ email, name }) {
  return paddleRequest("/customers", {
    method: "POST",
    body: { email, name }
  });
}

async function createPaddleDiscount({ percentOff, targetPlan, expiresAt, description, userId }) {
  const restrictTo = getPriceIdsForPlan(targetPlan);
  const body = {
    description: description || `User discount (${percentOff}% off, ${targetPlan})`,
    type: "percentage",
    amount: String(Math.min(100, Math.max(0.01, percentOff))),
    mode: "custom",
    usage_limit: 1,
    recur: false,
    expires_at: expiresAt.toISOString(),
    restrict_to: restrictTo.length > 0 ? restrictTo : null,
    custom_data: { userId: String(userId) }
  };
  const res = await paddleRequest("/discounts", { method: "POST", body });
  const id = res?.id;
  if (!id) throw new Error("Paddle discount creation failed: no ID returned");
  return id;
}

function getPriceIdsForPlan(targetPlan) {
  const ids = [];
  if (targetPlan === "pro") {
    if (config.paddle?.pricePro) ids.push(config.paddle.pricePro);
    if (config.paddle?.priceProYearly) ids.push(config.paddle.priceProYearly);
  } else if (targetPlan === "plus") {
    if (config.paddle?.pricePlus) ids.push(config.paddle.pricePlus);
    if (config.paddle?.pricePlusYearly) ids.push(config.paddle.pricePlusYearly);
  }
  return ids.filter(Boolean);
}

async function createPaddleTransaction({
  customerId,
  priceId,
  quantity = 1,
  customData,
  successUrl,
  cancelUrl,
  discountId
}) {
  const body = {
    items: [{ price_id: priceId, quantity }],
    customer_id: customerId,
    custom_data: customData
  };
  if (discountId) body.discount_id = discountId;
  if (successUrl || cancelUrl) {
    body.checkout = {
      success_url: successUrl,
      cancel_url: cancelUrl
    };
  }
  return paddleRequest("/transactions", { method: "POST", body });
}

async function listPaddleTransactions({ customerId, perPage = 10 }) {
  const params = new URLSearchParams();
  if (customerId) params.set("customer_id", customerId);
  params.set("per_page", String(perPage));
  return paddleRequest(`/transactions?${params.toString()}`);
}

async function createCustomerPortalSession({ customerId, returnUrl, subscriptionIds }) {
  const body = {};
  if (subscriptionIds?.length) body.subscription_ids = subscriptionIds;
  const session = await paddleRequest(`/customers/${customerId}/portal-sessions`, {
    method: "POST",
    body: Object.keys(body).length ? body : undefined
  });
  return rewritePortalUrlsForEnv(session);
}

async function resumePaddleSubscription(subscriptionId) {
  return paddleRequest(`/subscriptions/${subscriptionId}/resume`, {
    method: "POST",
    body: { effective_from: "immediately" }
  });
}

async function cancelPaddleSubscription(subscriptionId, { effectiveFrom = "next_billing_period" } = {}) {
  return paddleRequest(`/subscriptions/${subscriptionId}/cancel`, {
    method: "POST",
    body: { effective_from: effectiveFrom }
  });
}

async function activatePaddleSubscription(subscriptionId) {
  return paddleRequest(`/subscriptions/${subscriptionId}/activate`, { method: "POST" });
}

function updatePaddleSubscription(subscriptionId, body) {
  return paddleRequest(`/subscriptions/${subscriptionId}`, { method: "PATCH", body });
}

function verifyPaddleSignature(rawBody, signatureHeader) {
  if (!config.paddle?.webhookSecret) {
    throw new Error("PADDLE_WEBHOOK_SECRET is not configured");
  }
  if (!signatureHeader) {
    throw new Error("Missing Paddle signature header");
  }
  const parts = signatureHeader.split(/[,;]/).reduce((acc, part) => {
    const [key, value] = part.split("=");
    if (key && value) acc[key.trim()] = value.trim();
    return acc;
  }, {});
  const timestamp = parts.ts;
  const signature = parts.h1;
  if (!timestamp || !signature) throw new Error("Invalid Paddle signature header");
  const signedPayload = `${timestamp}:${rawBody}`;
  const computed = crypto
    .createHmac("sha256", config.paddle.webhookSecret)
    .update(signedPayload)
    .digest("hex");
  if (computed.length !== signature.length) throw new Error("Invalid Paddle webhook signature");
  const isValid = crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signature));
  if (!isValid) throw new Error("Invalid Paddle webhook signature");
  return true;
}

export {
  createCustomerPortalSession,
  createPaddleCustomer,
  createPaddleDiscount,
  createPaddleTransaction,
  listPaddleTransactions,
  activatePaddleSubscription,
  cancelPaddleSubscription,
  resumePaddleSubscription,
  updatePaddleSubscription,
  verifyPaddleSignature,
  isPaddleSandbox
};

4. Backend — Discount service (full code)

File: server/src/services/discountService.js

import { User } from "../modules/user/user.model.js";
import { Subscription } from "../modules/subscription/subscription.model.js";
import { UserDiscount } from "../modules/discount/discount.model.js";
import { getPlanId } from "../config/limits.js";
import {
  DISCOUNT_COOLDOWN_DAYS,
  DISCOUNT_VALIDITY_DAYS,
  RECENT_DISCOUNT_DAYS,
  getDiscountRule
} from "../config/discountRules.js";
import { logger } from "../config/logger.js";
import { config } from "../config/env.js";
import { enqueueEmailEvent } from "./emailEvents.js";
import { discountOfferEmail, FEATURE_LABELS } from "./emailTemplates.js";
import { createPaddleDiscount } from "./paddle.js";

async function checkEligibility(userId, trigger, context = {}) {
  const user = await User.findById(userId).select("marketingConsent subscriptionPlan deleted").lean();
  if (!user || user.deleted) {
    return { eligible: false, reason: "user_not_found_or_deleted" };
  }

  const subscription = await Subscription.findOne({ userId }).lean();
  const planId = getPlanId(subscription);
  const rule = getDiscountRule(trigger);
  if (!rule) return { eligible: false, reason: "unknown_trigger" };
  const targetPlan = rule.targetPlan || "pro";
  const PLAN_ORDER = ["free", "pro", "plus", "agency"];
  if (PLAN_ORDER.indexOf(planId) >= PLAN_ORDER.indexOf(targetPlan)) {
    return { eligible: false, reason: "already_on_target_plan" };
  }

  if (user.marketingConsent === false) {
    return { eligible: false, reason: "no_marketing_consent" };
  }

  const now = new Date();
  const recentThreshold = new Date(now.getTime() - RECENT_DISCOUNT_DAYS * 24 * 60 * 60 * 1000);
  const cooldownThreshold = new Date(now.getTime() - DISCOUNT_COOLDOWN_DAYS * 24 * 60 * 60 * 1000);

  const existingActive = await UserDiscount.findOne({ userId, status: "active" }).lean();
  if (existingActive) return { eligible: false, reason: "active_discount_exists" };

  const recentOrUsed = await UserDiscount.findOne({
    userId,
    $or: [
      { status: "used", usedAt: { $gte: cooldownThreshold } },
      { status: "expired", updatedAt: { $gte: cooldownThreshold } },
      { createdAt: { $gte: recentThreshold } }
    ]
  }).lean();
  if (recentOrUsed) return { eligible: false, reason: "cooldown_or_recent_discount" };

  if (trigger === "usage_limit_reached" && context.usage !== undefined) {
    const minUsage = rule.minUsageThisPeriod ?? 1;
    if (context.usage < minUsage) return { eligible: false, reason: "insufficient_usage" };
  }

  return { eligible: true };
}

async function evaluateAndCreateDiscount(userId, trigger, context = {}) {
  if (!config.discount?.enabled) {
    logger.debug({ userId, trigger }, "Discount system disabled");
    return { created: false, reason: "system_disabled" };
  }
  const result = await checkEligibility(userId, trigger, context);
  if (!result.eligible) {
    logger.debug({ userId, trigger, reason: result.reason }, "Discount eligibility check failed");
    return { created: false, reason: result.reason };
  }

  const rule = getDiscountRule(trigger);
  if (!rule) return { created: false, reason: "unknown_trigger" };

  const targetPlan = rule.targetPlan || "pro";
  const percentOff = rule.percentOff ?? rule.amountOff ?? 20;
  const expiresAt = new Date(Date.now() + DISCOUNT_VALIDITY_DAYS * 24 * 60 * 60 * 1000);

  let paymentDiscountId;
  try {
    paymentDiscountId = await createPaddleDiscount({
      percentOff,
      targetPlan,
      expiresAt,
      description: `User discount: ${trigger} (${percentOff}% off ${targetPlan})`,
      userId
    });
  } catch (err) {
    logger.error({ userId, trigger, err: err.message }, "Paddle discount creation failed");
    return { created: false, reason: "paddle_discount_failed" };
  }

  if (!paymentDiscountId) {
    logger.error({ userId, trigger }, "Paddle discount creation returned no ID");
    return { created: false, reason: "paddle_discount_failed" };
  }

  try {
    const discount = await UserDiscount.create({
      userId,
      paymentProvider: "paddle",
      paymentDiscountId,
      trigger,
      targetPlan,
      discountType: rule.percentOff ? "percent_off" : "amount_off",
      discountValue: percentOff,
      expiresAt,
      status: "active",
      metadata: context
    });

    logger.info(
      { userId, discountId: discount._id, paymentDiscountId, trigger },
      "Discount created (Paddle + DB)"
    );

    if (paymentDiscountId && discount.status === "active") {
      const user = await User.findById(userId).select("email name").lean();
      if (user?.email) {
        const emailContext =
          trigger === "usage_limit_reached" && context.feature
            ? { ...context, featureLabel: FEATURE_LABELS[context.feature] || context.feature }
            : context;
        const { html, text, subject } = discountOfferEmail(user, trigger, rule, emailContext);
        await enqueueEmailEvent({
          eventId: `discount-offer:${userId}:${discount._id}`,
          type: "discount-offer",
          to: user.email,
          subject,
          text,
          html
        });
      }
    }

    return { created: true, discount };
  } catch (err) {
    const isDuplicateKey =
      err.code === 11000 ||
      err.writeErrors?.some?.((e) => e?.err?.code === 11000);
    if (isDuplicateKey) {
      logger.debug({ userId, trigger }, "Discount already exists (race condition)");
      return { created: false, reason: "already_exists" };
    }
    logger.error({ userId, trigger, err: err.message }, "Failed to create discount");
    return { created: false, reason: "creation_failed" };
  }
}

async function getActiveDiscount(userId) {
  const now = new Date();
  return UserDiscount.findOne({
    userId,
    status: "active",
    expiresAt: { $gt: now }
  }).lean();
}

async function markDiscountUsed(userId, discountId) {
  const discount = await UserDiscount.findOne({
    _id: discountId,
    userId,
    status: "active"
  });
  if (!discount) return false;
  discount.status = "used";
  discount.usedAt = new Date();
  await discount.save();
  logger.info({ userId, discountId, paymentDiscountId: discount.paymentDiscountId }, "Discount marked as used");
  return true;
}

async function markDiscountUsedByPaymentId(userId, paymentDiscountId) {
  const discount = await UserDiscount.findOne({
    userId,
    paymentDiscountId,
    status: "active"
  });
  if (!discount) return false;
  return markDiscountUsed(userId, discount._id);
}

export {
  checkEligibility,
  evaluateAndCreateDiscount,
  getActiveDiscount,
  markDiscountUsed,
  markDiscountUsedByPaymentId
};

5. Backend — Subscription routes, schema, controller (code)

Routes: server/src/modules/subscription/subscription.route.js

import { Router } from "express";
import { validate } from "../../middlewares/validate.js";
import { requireAuth } from "../../middlewares/auth.js";
import { upgradeSubscriptionSchema, cancelSubscriptionSchema } from "./subscription.schema.js";
import { getPlans, getCurrent, upgrade, cancel, getBilling, createBillingPortal, resume, getUsageEndpoint } from "./subscription.controller.js";

const subscriptionRouter = Router();

subscriptionRouter.use(requireAuth);
subscriptionRouter.get("/plans", getPlans);
subscriptionRouter.get("/current", getCurrent);
subscriptionRouter.get("/usage", getUsageEndpoint);
subscriptionRouter.post("/upgrade", validate(upgradeSubscriptionSchema), upgrade);
subscriptionRouter.post("/cancel", validate(cancelSubscriptionSchema), cancel);
subscriptionRouter.get("/billing", getBilling);
subscriptionRouter.post("/billing-portal", createBillingPortal);
subscriptionRouter.post("/resume", resume);

export { subscriptionRouter };

Schema: server/src/modules/subscription/subscription.schema.js

import { z } from "zod";

const upgradeSubscriptionSchema = z.object({
  body: z.object({
    plan: z.enum(["free", "pro", "plus", "agency"]),
    interval: z.enum(["monthly", "yearly"]).optional().default("monthly")
  }),
  query: z.object({}).optional(),
  params: z.object({}).optional()
});

const cancelSubscriptionSchema = z.object({
  body: z.object({}).optional(),
  query: z.object({}).optional(),
  params: z.object({}).optional()
});

export { upgradeSubscriptionSchema, cancelSubscriptionSchema };

Controller — getCurrent (with active_discount):

const getCurrent = asyncHandler(async (req, res) => {
  const { billingUserId, billingOwnerName, isSharedContext } = await resolveBillingContext(req);
  const subscription = await Subscription.findOne({ userId: billingUserId }).lean();
  const payload = buildCanonicalSubscriptionResponse(
    subscription,
    billingUserId,
    billingOwnerName,
    isSharedContext
  );
  if (payload && !isSharedContext) {
    const activeDiscount = await getActiveDiscount(billingUserId);
    if (activeDiscount) {
      payload.active_discount = {
        discount_value: activeDiscount.discountValue,
        discount_type: activeDiscount.discountType,
        target_plan: activeDiscount.targetPlan,
        expires_at: activeDiscount.expiresAt
      };
    } else {
      payload.active_discount = null;
    }
  }
  return ok(res, payload, "Current plan fetched");
});

Controller — upgrade (checkout path: attach discount only when plan matches; retry on discount_usage_limit_exceeded):

// No effective subscription: create first subscription via checkout transaction.
const priceIdToUse = hasUsedTrial || !trialPriceId ? paidPriceId : trialPriceId;

const billingUser = await User.findById(billingUserId).select("paddleCustomerId email name").lean();
let customerId = billingUser?.paddleCustomerId;
if (!customerId) {
  const customer = await createPaddleCustomer({
    email: billingUser?.email ?? req.user.email,
    name: billingUser?.name ?? req.user.name
  });
  customerId = customer?.id;
  if (!customerId) {
    throw new AppError("Failed to create Paddle customer", StatusCodes.INTERNAL_SERVER_ERROR);
  }
  await User.findByIdAndUpdate(billingUserId, { paddleCustomerId: customerId });
}

const activeDiscount = await getActiveDiscount(billingUserId);
const selectedPlan = req.body.plan;
const discountAppliesToSelectedPlan = activeDiscount && String(activeDiscount.targetPlan) === String(selectedPlan);
let discountId = discountAppliesToSelectedPlan ? (activeDiscount?.paymentDiscountId || null) : null;
if (discountAppliesToSelectedPlan && activeDiscount && !discountId) {
  logger.warn({ userId: billingUserId, discountId: activeDiscount._id }, "Discount has no paymentDiscountId — checkout will open without discount");
}
const customData = {
  userId: String(billingUserId),
  plan: req.body.plan,
  interval
};
if (discountId && activeDiscount?._id) {
  customData.discountId = String(activeDiscount._id);
}

let transaction;
try {
  transaction = await createPaddleTransaction({
    customerId,
    priceId: priceIdToUse,
    customData,
    discountId,
    successUrl: `${config.app.frontendBaseUrl}/subscription?success=1`,
    cancelUrl: `${config.app.frontendBaseUrl}/subscription?canceled=1`
  });
} catch (err) {
  const code = err?.payload?.error?.code;
  if (code === "discount_usage_limit_exceeded" && activeDiscount?._id) {
    await markDiscountUsed(billingUserId, String(activeDiscount._id));
    logger.info({ userId: billingUserId, discountId: activeDiscount._id }, "Discount exhausted in Paddle — marked used, retrying without discount");
    delete customData.discountId;
    transaction = await createPaddleTransaction({
      customerId,
      priceId: priceIdToUse,
      customData,
      discountId: null,
      successUrl: `${config.app.frontendBaseUrl}/subscription?success=1`,
      cancelUrl: `${config.app.frontendBaseUrl}/subscription?canceled=1`
    });
  } else {
    throw err;
  }
}

const checkoutUrl =
  transaction?.checkout_url ||
  transaction?.checkoutUrl ||
  transaction?.checkout?.url ||
  transaction?.checkout?.checkout_url ||
  transaction?.url;
if (!checkoutUrl) {
  throw new AppError("Paddle checkout URL not available", StatusCodes.INTERNAL_SERVER_ERROR);
}

return ok(res, { checkoutUrl }, "Checkout session created");

Controller — createBillingPortal:

const createBillingPortal = asyncHandler(async (req, res) => {
  const customerId = req.user.paddleCustomerId;
  if (!customerId) {
    throw new AppError(
      "Billing portal is available after your first payment. Complete a subscription to manage billing.",
      StatusCodes.BAD_REQUEST
    );
  }
  const subscription = await Subscription.findOne({ userId: req.user._id }).select("paddleSubscriptionId").lean();
  const subscriptionIds = subscription?.paddleSubscriptionId ? [subscription.paddleSubscriptionId] : undefined;
  const session = await createCustomerPortalSession({
    customerId,
    returnUrl: `${config.app.frontendBaseUrl}/subscription`,
    subscriptionIds
  });
  const url =
    session?.urls?.general?.overview ||
    session?.url ||
    session?.customer_portal_url ||
    session?.portal_url ||
    session?.data?.urls?.general?.overview ||
    session?.data?.url;
  if (!url) {
    throw new AppError("Paddle customer portal URL not available", StatusCodes.INTERNAL_SERVER_ERROR);
  }
  return ok(res, { url }, "Billing portal created");
});

6. Backend — Webhook (full code)

Route: yt-analytics-studio-server/src/modules/webhook/webhook.route.js

import { Router } from "express";
import { handlePaddleWebhook } from "./webhook.controller.js";

const webhookRouter = Router();
webhookRouter.post("/paddle", handlePaddleWebhook);
export { webhookRouter };

Controller (signature, event parsing, transaction.paid/completed with discount mark-used, transaction failed/canceled/expired, subscription events, one-subscription invariant):

File: server/src/modules/webhook/webhook.controller.js — behavior summary and critical code:

Verification: Read req.body as raw (Buffer/string). Header paddle-signature or Paddle-Signature. Call verifyPaddleSignature(rawBody, signature). On failure return 400 with message.
Parse: event = JSON.parse(rawBody). eventType = event?.event_type || event?.eventType || event?.type. data = event?.data || {}, customData = data?.custom_data || data?.customData || {}.
Resolve userId: From customData.userId, else from data.customer_id via User lookup by paddleCustomerId, else for subscription.* from Subscription by paddleSubscriptionId.
Price/plan: priceId = data?.items?.[0]?.price_id || .... Map priceId to plan/interval via config (e.g. resolvePlanIntervalFromPriceId). Prefer inferred plan from price_id over custom_data.plan.
One-subscription invariant: If user has existing effective subscription (active/trialing/cancelled_at_period_end) and incomingPaddleSubscriptionId !== existingPaddleSubscriptionId, return res.json({ received: true, ignored: true }).
transaction.paid / transaction.completed: Update Subscription (plan, interval, price, currentPeriodEnd, paddleSubscriptionId, paddleTransactionId, status active if price > 0; clear nextPlan when plan matches). Update User (subscriptionPlan, paddleCustomerId). Discount: discountId = customData?.discountId, paddleDiscountId = data?.discount_id || data?.discount?.id. If discountId then markDiscountUsed(userId, discountId); else if paddleDiscountId then markDiscountUsedByPaymentId(userId, paddleDiscountId).
transaction.canceled / transaction.expired / transaction.failed: Optionally evaluateAndCreateDiscount(userId, "upgrade_flow_abandoned", { transactionId, plan }) (fire-and-forget).
transaction.expired / subscription.expired: Set subscription to free, clear Paddle IDs.
subscription.created / subscription.updated with status trialing: Do not overwrite if current status is already "active". Else update Subscription (status trialing, trialingEndsAt, plan from custom or existing).
subscription.canceled / subscription.updated: Handle cancelled_at_period_end (nextPlan free, currentPeriodEnd) or immediate cancel (plan free, clear IDs). Also handle resumed/activated (status active, clear nextPlan).

(Full webhook controller is ~330 lines; the logic above is the exact behavior. Refer to webhook.controller.js in repo for the complete implementation.)

7. Backend — Discount routes, controller, model (code)

Route: server/src/modules/discount/discount.route.js

import { Router } from "express";
import { requireAuth, requireAdmin } from "../../middlewares/auth.js";
import { getAnalytics } from "./discount.controller.js";

const discountRouter = Router();
discountRouter.get("/analytics", requireAuth, requireAdmin, getAnalytics);
export { discountRouter };

Controller: server/src/modules/discount/discount.controller.js

const getAnalytics = asyncHandler(async (req, res) => {
  const triggers = [
    "usage_limit_reached",
    "locked_feature_accessed",
    "upgrade_flow_abandoned",
    "inactivity_after_usage"
  ];

  const byTrigger = {};
  for (const trigger of triggers) {
    const [created, used] = await Promise.all([
      UserDiscount.countDocuments({ trigger, status: { $in: ["active", "used", "expired"] } }),
      UserDiscount.countDocuments({ trigger, status: "used" })
    ]);
    byTrigger[trigger] = { created, used, conversionRate: created > 0 ? (used / created * 100).toFixed(1) + "%" : "0%" };
  }

  const [totalCreated, totalUsed, activeCount] = await Promise.all([
    UserDiscount.countDocuments({ status: { $in: ["active", "used", "expired"] } }),
    UserDiscount.countDocuments({ status: "used" }),
    UserDiscount.countDocuments({ status: "active", expiresAt: { $gt: new Date() } })
  ]);

  return ok(res, {
    byTrigger,
    summary: {
      totalCreated,
      totalUsed,
      activeCount,
      conversionRate: totalCreated > 0 ? (totalUsed / totalCreated * 100).toFixed(1) + "%" : "0%"
    }
  }, "Discount analytics");
});

Model: server/src/modules/discount/discount.model.js

const discountSchema = new mongoose.Schema(
  {
    userId: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
    paymentDiscountId: { type: String, index: true },
    paymentProvider: { type: String, enum: ["paddle"], default: "paddle" },
    trigger: {
      type: String,
      enum: [
        "usage_limit_reached",
        "locked_feature_accessed",
        "upgrade_flow_abandoned",
        "inactivity_after_usage"
      ],
      required: true
    },
    targetPlan: { type: String, enum: ["pro", "plus"], required: true },
    discountType: { type: String, enum: ["percent_off", "amount_off"], required: true },
    discountValue: { type: Number, required: true },
    expiresAt: { type: Date, required: true, index: true },
    status: { type: String, enum: ["active", "used", "expired"], default: "active", index: true },
    usedAt: { type: Date },
    metadata: { type: mongoose.Schema.Types.Mixed },
    createdAt: { type: Date, default: Date.now }
  },
  { timestamps: true }
);

discountSchema.index({ userId: 1, status: 1 });
discountSchema.index({ status: 1, expiresAt: 1 });
discountSchema.index(
  { userId: 1 },
  { unique: true, partialFilterExpression: { status: "active" } }
);

const UserDiscount = mongoose.model("UserDiscount", discountSchema);

8. Backend — Models and config

Subscription model: server/src/modules/subscription/subscription.model.js

Fields: userId, plan, status (active, cancelled, cancelled_at_period_end, expired, trialing, canceled), nextPlan, interval, price, currentPeriodEnd, trialingEndsAt, paddleSubscriptionId, paddleTransactionId.

Discount rules: server/src/config/discountRules.js

usage_limit_reached: percentOff (env), targetPlan "pro", minUsageThisPeriod.
locked_feature_accessed: percentOff, targetPlan "pro".
upgrade_flow_abandoned: percentOff, targetPlan "pro".
inactivity_after_usage: percentOff, targetPlan "pro", inactivityDays, minUsagePreviousPeriod.
Exports: DISCOUNT_COOLDOWN_DAYS, DISCOUNT_VALIDITY_DAYS, RECENT_DISCOUNT_DAYS, getDiscountRule(trigger).

Env config (paddle + discount): server/src/config/env.js

config.paddle: apiKey, environment, webhookSecret, pricePro, priceProYearly, pricePlus, pricePlusYearly, priceAgency, priceProTrial, priceProYearlyTrial, pricePlusTrial, pricePlusYearlyTrial.
config.app.frontendBaseUrl.
config.discount: enabled, percentOffUsageLimit, percentOffLockedFeature, percentOffAbandoned, percentOffInactivity, validityDays, cooldownDays.

9. Frontend — Subscription API (full code)

File: client/src/api/subscription.ts

import { apiClient } from "./client";

export interface Plan {
  id: string;
  name: string;
  price: number | null;
  yearlyPrice?: number | null;
  yearlySavings?: number | null;
  popular?: boolean;
  target?: string;
  priceNote?: string;
  contactSales?: boolean;
  comingSoon?: boolean;
  features: string[];
}

export type SubscriptionStatus =
  | "active"
  | "trialing"
  | "cancelled"
  | "cancelled_at_period_end"
  | "expired";

export type PlanId = "free" | "pro" | "plus" | "agency";

export type BillingInterval = "monthly" | "yearly";

export interface ActiveDiscount {
  discount_value: number;
  discount_type: "percent_off" | "amount_off";
  target_plan: string;
  expires_at: string;
}

export interface CurrentSubscriptionResponse {
  current_plan: PlanId;
  subscription_status: SubscriptionStatus;
  next_plan: PlanId | null;
  current_period_end: string | null;
  trialing_ends_at: string | null;
  billing_interval?: BillingInterval | null;
  plan?: string;
  status?: string;
  nextPlan?: string | null;
  currentPeriodEnd?: string | null;
  billingUserId?: string;
  billingOwnerName?: string;
  isSharedContext?: boolean;
  active_discount?: ActiveDiscount | null;
  [key: string]: unknown;
}

export async function fetchSubscriptionPlans() {
  const { data } = await apiClient.get("/subscription/plans");
  return data.data as Plan[];
}

export async function fetchCurrentSubscription(channelId?: string) {
  const { data } = await apiClient.get("/subscription/current", {
    params: channelId ? { channelId } : undefined
  });
  return data.data as CurrentSubscriptionResponse | null;
}

export interface UpgradeSubscriptionResponse {
  checkoutUrl?: string;
  plan?: PlanId;
  currentPlan?: PlanId;
  nextPlan?: PlanId;
  activated?: boolean;
}

export async function upgradeSubscription(plan: string, interval: BillingInterval = "monthly") {
  const { data } = await apiClient.post("/subscription/upgrade", { plan, interval });
  return data.data as UpgradeSubscriptionResponse;
}

export async function cancelSubscription() {
  const { data } = await apiClient.post("/subscription/cancel");
  return data.data as CurrentSubscriptionResponse;
}

export async function createBillingPortal() {
  const { data } = await apiClient.post("/subscription/billing-portal");
  return data.data as { url: string };
}

export async function resumeSubscription() {
  const { data } = await apiClient.post("/subscription/resume");
  return data.data as CurrentSubscriptionResponse;
}

export type UsageEntry = { used: number; limit: number | typeof Infinity | "infinity" };
export type UsageLimits = Record<string, UsageEntry>;

export async function fetchSubscriptionUsage(channelId?: string) {
  const { data } = await apiClient.get("/subscription/usage", {
    params: channelId ? { channelId } : undefined
  });
  return data.data as {
    usage: UsageLimits;
    planId: string;
    billingUserId?: string;
    billingOwnerName?: string;
    isSharedContext?: boolean;
  };
}

10. Frontend — Subscription page (key code)

File: client/src/pages/Subscription.tsx

Imports and queries:

import { fetchSubscriptionPlans, fetchCurrentSubscription, upgradeSubscription, createBillingPortal, resumeSubscription, fetchSubscriptionUsage, type Plan, type BillingInterval, type SubscriptionStatus } from '@/api/subscription';

const { data: plans = [], isLoading: isLoadingPlans } = useQuery({
  queryKey: ["subscription", "plans"],
  queryFn: fetchSubscriptionPlans,
  enabled: !!user,
});

const { data: currentSubscription, isLoading: isLoadingCurrent } = useQuery({
  queryKey: ["subscription", "current", contextChannelId ?? "me"],
  queryFn: () => fetchCurrentSubscription(contextChannelId),
  enabled: !!user,
});

const { data: usage } = useQuery({
  queryKey: ["subscription", "usage", contextChannelId ?? "me"],
  queryFn: () => fetchSubscriptionUsage(contextChannelId),
  enabled: !!user,
});

const upgradeMutation = useMutation({
  mutationFn: (vars: { plan: string; interval: BillingInterval }) =>
    upgradeSubscription(vars.plan, vars.interval),
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ["subscription"] });
    dispatch(initializeSession());
  },
});

const portalMutation = useMutation({ mutationFn: () => createBillingPortal() });
const resumeMutation = useMutation({
  mutationFn: () => resumeSubscription(),
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ['subscription'] });
    dispatch(initializeSession());
    toast.success('Subscription resumed. Your plan will continue as before.');
  },
});

Derived state from current subscription:

const currentPlan = (currentSubscription?.current_plan ?? currentSubscription?.plan ?? user?.subscriptionPlan ?? 'free') as string;
const subscriptionStatus = (currentSubscription?.subscription_status ?? ...) as SubscriptionStatus;
const nextPlan = currentSubscription?.next_plan ?? currentSubscription?.nextPlan ?? null;
const currentPeriodEnd = currentSubscription?.current_period_end ?? currentSubscription?.currentPeriodEnd ?? null;
const trialingEndsAt = currentSubscription?.trialing_ends_at ?? null;
const currentInterval = (currentSubscription?.billing_interval ?? currentSubscription?.interval ?? 'monthly') as BillingInterval;
const activeDiscount = currentSubscription?.active_discount ?? null;

Upgrade handler (redirect to checkout when checkoutUrl returned):

const handleUpgrade = async (plan: Plan) => {
  if (plan.comingSoon) { /* mailto get notified */ return; }
  if (plan.contactSales) { /* mailto contact sales */ return; }
  try {
    const data = await upgradeMutation.mutateAsync({ plan: plan.id, interval: billingInterval });
    if (data?.checkoutUrl) {
      window.location.href = data.checkoutUrl;
      return;
    }
    if (data?.nextPlan != null && data?.currentPlan != null) {
      toast.success('Downgrade scheduled for next billing cycle. Your current plan stays active until then.');
    } else {
      toast.success(`Switched to ${plan.name} plan.`);
    }
  } catch (error) {
    toast.error('Failed to update subscription. Please try again.');
  }
};

Active discount badge and copy (current plan card):

{activeDiscount && (
  <Badge className="bg-emerald-600 ...">
    <Tag className="h-3 w-3" />
    {activeDiscount.discount_type === 'percent_off'
      ? `${activeDiscount.discount_value}% off`
      : `$${activeDiscount.discount_value} off`}{' '}
    on upgrade
  </Badge>
)}
{activeDiscount && (
  <div className="rounded-lg border border-emerald-500/30 ...">
    <p className="font-medium">You have an active discount</p>
    <p className="text-muted-foreground mt-0.5">
      {activeDiscount.discount_type === 'percent_off'
        ? `${activeDiscount.discount_value}% off`
        : `$${activeDiscount.discount_value} off`}{' '}
      when you upgrade to {activeDiscount.target_plan}. Expires{' '}
      {new Date(activeDiscount.expires_at).toLocaleDateString(undefined, { dateStyle: 'medium' })}.
      Applied automatically at checkout — no code needed.
    </p>
  </div>
)}

Billing portal (Manage billing / Payment method):

<Button
  variant="outline"
  size="sm"
  onClick={async () => {
    try {
      const data = await portalMutation.mutateAsync();
      window.location.href = data.url;
    } catch (error: unknown) {
      toast.error(extractErrorMessage(error as any) || 'Failed to open billing portal');
    }
  }}
  disabled={portalMutation.isPending}
>
  Manage billing
</Button>

Resume subscription (when status is cancelled_at_period_end):

<Button
  variant="default"
  size="sm"
  onClick={async () => {
    try {
      await resumeMutation.mutateAsync();
    } catch (error: unknown) {
      toast.error(extractErrorMessage(error as any) || 'Failed to resume subscription');
    }
  }}
  disabled={resumeMutation.isPending}
>
  Resume subscription
</Button>

Plan cards: Toggle monthly/yearly; for each plan, button calls handleUpgrade(plan). Success/cancel URLs point to /subscription?success=1 and /subscription?canceled=1 (configured in backend when creating transaction).

11. Edge cases and checklist

Edge cases

Sandbox vs production: Never mix API key, price IDs, or discount IDs between environments.
Discount not eligible: Attach discount only when req.body.plan === activeDiscount.targetPlan to avoid Paddle "discount not eligible for items".
discount_usage_limit_exceeded: In upgrade flow, catch this Paddle error, call markDiscountUsed(userId, activeDiscount._id), then retry createPaddleTransaction without discountId.
Webhook discount mark-used: Prefer customData.discountId; fallback to data.discount_id or data.discount?.id and markDiscountUsedByPaymentId(userId, paddleDiscountId).
One subscription per user: In webhook, if user already has an effective subscription and event is for a different subscription_id, return { received: true, ignored: true }.
Portal URLs in sandbox: Backend rewrites production portal host to sandbox portal host when PADDLE_ENVIRONMENT=sandbox.

Checklist for new Paddle work

[ ] All price IDs and API key match same Paddle environment.
[ ] Webhook secret set; endpoint receives raw body for signature verification.
[ ] New discount: create in Paddle first; store paymentDiscountId; attach at checkout only when selected plan matches target_plan.
[ ] Webhook marks discount used (by internal ID or Paddle discount ID) on transaction.paid/completed.
[ ] Handle discount_usage_limit_exceeded by marking used and retrying without discount.
[ ] Frontend: upgrade calls POST /api/subscription/upgrade, redirects to data.checkoutUrl when present.
[ ] Success/cancel URLs configured in backend when creating transaction (e.g. ${frontendBaseUrl}/subscription?success=1).

This README plus the repo contains every endpoint and the full code for Paddle subscription, checkout, discounts, and webhooks. When changing behavior, update this file and the relevant source files together.

Add SSH to Github

Arshan Nawaz — Wed, 09 Oct 2024 17:15:42 +0000

Step 1: Generate a new SSH key

ssh-keygen -t ed25519 -C "email@example.com" -f ~/.ssh/key-path

Step 2: Display the public key (use this to add to GitHub)

cat ~/.ssh/key-path.pub

Step 3: Start the SSH agent

eval "$(ssh-agent -s)"

Step 4: Add the new key to the SSH agent

ssh-add ~/.ssh/key-path

Step 5: Edit the SSH config file to specify which key to use for GitHub

nano ~/.ssh/config

Inside the config file, add the following:

Host github.com
   HostName github.com
  User git
   IdentityFile ~/.ssh/key-path

Step 6: Set appropriate permissions for the .ssh directory and the keys

chmod 700 ~/.ssh              # Permissions for the .ssh folder
chmod 600 ~/.ssh/key-path      # Permissions for the private key
chmod 644 ~/.ssh/key-path.pub  # Permissions for the public key

Step 7: Test the connection to GitHub

ssh -T git@github.com

Setting up Stripe Checkout with MERN STACK

Arshan Nawaz — Sat, 28 Sep 2024 10:45:48 +0000

In this guide, we'll walk through creating a Stripe checkout session for an online service, using Node.js and MongoDB. We'll cover key steps like calculating prices, creating a Stripe checkout session, and handling webhooks to process orders.

1. Setting Up Stripe Checkout

npm install stripe

Next, initialize Stripe with your secret key:

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

2. Price Calculation Function:

// Sample price calculation based on cart items
async function calculateTotalPrice(cartItems) {
  let totalPrice = 0;
  for (const item of cartItems) {
    totalPrice += item.price * item.quantity;
  }
  return totalPrice;
}

3. Create Checkout Session Function:

export const createCheckoutSession = async (req, res) => {
  try {
    const { cartItems } = req.body; // Expecting cartItems array in request body

    // Sample cart data
    const sampleCartItems = [
      {
        itemId: "1",
        itemName: "Leather Bag",
        quantity: 1,
        price: 50.00, // in USD
        currency: "USD",
        description: "A stylish leather bag",
        image: "https://example.com/images/leather-bag.jpg"
      },
      {
        itemId: "2",
        itemName: "Cotton Shirt",
        quantity: 2,
        price: 25.00, // in USD
        currency: "USD",
        description: "A soft cotton shirt",
        image: "https://example.com/images/cotton-shirt.jpg"
      }
    ];

    // Calculate total price
    const totalPrice = await calculateTotalPrice(sampleCartItems);

    // Create a Stripe customer for this checkout session
    const customer = await stripe.customers.create({
      metadata: {
        cartItems: JSON.stringify(sampleCartItems), // Storing cart in metadata
      }
    });

    // Prepare line items for Stripe
    const line_items = sampleCartItems.map(item => ({
      price_data: {
        currency: item.currency,
        product_data: {
          name: item.itemName,
          description: item.description,
          images: [item.image],
        },
        unit_amount: Math.round(item.price * 100),  // Convert price to cents
      },
      quantity: item.quantity,
    }));

    // Create Stripe checkout session
    const session = await stripe.checkout.sessions.create({
      payment_method_types: ["card"],
      line_items,
      mode: "payment",
      customer: customer.id,
      success_url: `${req.headers.origin}/checkout-success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${req.headers.origin}/checkout-cancelled`,
    });

    res.send({ url: session.url });
  } catch (err) {
    console.error("Checkout session creation error:", err);
    res.status(500).send({ error: "Failed to create checkout session." });
  }
};

4. Handle Stripe Webhook:

const createOrder = async (customer, data) => {
  const cartItems = JSON.parse(customer.metadata.cartItems);

  const newOrder = new Order({
    customerId: customer.id,
    cartItems: cartItems,  // Store cart items in the order
    payment_status: data.payment_status,
    payment_intent: data.payment_intent,
    totalAmount: data.amount_total / 100,  // Convert from cents to dollars
    status: "PROCESSING",
    createdAt: new Date(),
  });

  try {
    await newOrder.save();

    // Send a notification after order creation
    const notification = new Notification({
      userId: customer.id,
      orderId: newOrder._id,
      message: `Your order with ID ${newOrder._id} was successfully created.`,
    });
    await notification.save();
  } catch (err) {
    console.error("Failed to save order:", err);
  }
};

export const handleStripeWebhook = async (req, res) => {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
  let event;

  try {
    const signature = req.headers["stripe-signature"];
    event = stripe.webhooks.constructEvent(req.body, signature, webhookSecret);
  } catch (err) {
    console.log(`⚠️  Webhook signature verification failed: ${err.message}`);
    return res.sendStatus(400);
  }

  const data = event.data.object;
  const eventType = event.type;

  if (eventType === "checkout.session.completed") {
    stripe.customers.retrieve(data.customer)
      .then(async (customer) => {
        try {
          await createOrder(customer, data);
        } catch (err) {
          console.error("Error creating order:", err);
        }
      })
      .catch(err => console.error("Error retrieving customer:", err));
  }

  res.status(200).end();
};

5. Handling routes

// Adjust controllers and path 
import express from "express";
import { createCheckoutSession, handleStripeWebhook } from "../controllers/payment/payment.js";
import { isUser } from "../middleware/auth.js";
import bodyParser from "body-parser";

const router = express.Router();

// Stripe Checkout Session route
router.post("/create-checkout-session",  express.json({ type: "application/json" }),isUser, createCheckoutSession);

// Use the raw body parser only for Stripe webhooks
router.post('/webhook', express.raw({ type: 'application/json' }), handleStripeWebhook);

export default router;

Put this toute above these middleware
app.use("/payment", payment);

// only use the raw bodyParser for webhooks
app.use((req, res, next) => {
    if (req.originalUrl === '/webhook') {
        next();
    } else { 
        express.json({limit: '5mb'})(req, res, next);
    }
});
app.use(express.static("public"));
app.use(express.urlencoded({ extended: true }));
app.use(express.json({ limit: "10mb" }));

*6. Frontend *

 const handleStripeCheckout = async () => {
        setIsLoading(true);
        try {
          const response = await api.post(`${config.BASE_URL}/payment/create-checkout-session`, {
            cartItems,
          });

          console.log("Stripe response:", response); // Log the response
          if (response.data.url) {
            window.location.href = response.data.url; // Redirect to Stripe checkout
          } else {
            console.error("No URL returned from Stripe:", response.data);
          }
        } catch (err) {
          console.error("Stripe Checkout Error:", err);
          Swal.fire({
            title: "Error",
            text: "There was an issue processing your payment.",
            icon: "error",
            confirmButtonText: "OK",
          });
        }
        setIsLoading(false);
      };

7. Tailwind Success Page ( optional )

import React from 'react'
import { Link } from 'react-router-dom'

function CheckoutSuccess() {
  return (
    <div className="h-screen flex justify-center items-center bg-gray-100">
      <div className="bg-white p-6 rounded-lg shadow-md text-center max-w-md">
        <svg viewBox="0 0 24 24" className="text-green-600 w-16 h-16 mx-auto my-6">
          <path fill="currentColor"
            d="M12,0A12,12,0,1,0,24,12,12.014,12.014,0,0,0,12,0Zm6.927,8.2-6.845,9.289a1.011,1.011,0,0,1-1.43.188L5.764,13.769a1,1,0,1,1,1.25-1.562l4.076,3.261,6.227-8.451A1,1,0,1,1,18.927,8.2Z">
          </path>
        </svg>
        <h3 className="md:text-2xl text-base text-gray-900 font-semibold">Payment Done!</h3>
        <p className="text-gray-600 my-2">Thank you for completing your secure online payment.</p>
        <p>Have a great day!</p>
        <div className="py-10">
          <Link to="/orders" className="px-12 bg-indigo-600 hover:bg-indigo-500 text-white font-semibold py-3 rounded-lg">
            Go to Orders
          </Link>
        </div>
      </div>
    </div>
  )
}

export default CheckoutSuccess

8. Tailwind Cancel Page ( optional )

import React from 'react'
import { Link } from 'react-router-dom'

function CheckoutCancel() {
  return (
    <div className="h-screen flex justify-center items-center bg-gray-100">
      <div className="bg-white p-6 rounded-lg shadow-md text-center max-w-md">
        <svg viewBox="0 0 24 24" className="text-red-600 w-16 h-16 mx-auto my-6">
          <path fill="currentColor"
            d="M12 2a10 10 0 1 0 10 10A10 10 0 0 0 12 2Zm1 14.93V17a1 1 0 1 1-2 0v-1.07a6.84 6.84 0 0 1-4.6-4.6H7a1 1 0 1 1 0-2H6.4A6.84 6.84 0 0 1 11 6.07V5a1 1 0 1 1 2 0v1.07a6.84 6.84 0 0 1 4.6 4.6H17a1 1 0 1 1 0 2h.6A6.84 6.84 0 0 1 13 15.93Z">
          </path>
        </svg>
        <h3 className="md:text-2xl text-base text-gray-900 font-semibold">Payment Cancelled</h3>
        <p className="text-gray-600 my-2">Your payment has been cancelled. You can continue shopping or try again later.</p>
        <div className="py-10">
          <Link to="/" className="px-12 bg-red-600 hover:bg-red-500 text-white font-semibold py-3 rounded-lg">
            Continue Shopping
          </Link>
        </div>
      </div>
    </div>
  )
}

export default CheckoutCancel

9. Conclusion:

This backend example demonstrates how to:
Create a Stripe checkout session with sample cart items (like a bag and a shirt).
Handle price calculations based on cart items.
Use Stripe webhooks to handle completed payments and save orders to the database.

Setting Up ESLint and Prettier in Your Node.js App with Pre-Commit Hooks

Arshan Nawaz — Mon, 26 Aug 2024 07:11:19 +0000

To set up ESLint and Prettier in your Node.js app with pre-commit hooks, follow these steps:

1. Install Dependencies
Run the following command to install the necessary dependencies:

npm install --save-dev @commitlint/cli @commitlint/config-conventional @eslint/js eslint eslint-config-prettier eslint-plugin-prettier globals prettier husky lint-staged

2. Configure ESLint
Create a .eslint.config.js file in the root directory:

import js from '@eslint/js';

export default [
  js.configs.recommended,
  {
    languageOptions: {
      globals: {
        console: true,
        process: true,
      },
    },
    rules: {
      'no-console': ['error', { allow: ['warn', 'error'] }], // Allow console.warn and console.error
      'no-unused-vars': ['off', {
        vars: 'all', // Check all
        args: 'after-used', // Ignore unused variables after they are used
        ignoreRestSiblings: false, // Ignore unused variables that are rest siblings
        varsIgnorePattern: '^_', // Ignore unused variables starting with an underscore
        argsIgnorePattern: '^_', // Ignore unused variables starting with an underscore
      }], // Warn on unused variables
      'no-undef': ['off',{
        typeof: true,
      }], // Error on undefined variables
      'quotes': ['error', 'single', { allowTemplateLiterals: true }], // Use single quotes
    },
  },
];

3. Configure Prettier
Create a .prettierrc file in the root directory:

{
    "trailingComma": "none",
    "tabWidth": 4,
    "semi": false,
    "singleQuote": true,
    "bracketSameLine": true,
    "printWidth": 150,
    "singleAttributePerLine": true,
    "endOfLine": "crlf"
}

4. Configure Commitlint
Create a commitlint.config.js file in the root directory:

module.exports = {
    extends: ['@commitlint/cli', '@commitlint/config-conventional'],
    rules: {
        'type-enum': [
            2,
            'always',
            [
                'feat',  // feat: implement user profile page
                'fix',  // fix: correct typo in user profile page
                'docs', // docs: add jsdoc to user profile page
                'style', // style: add css to user profile page
                'refactor', // refactor: extract user profile page to component
                'perf', // perf: improve user profile page load time
                'test', // test: add unit test for user profile page
                'build', // build: update webpack config
                'ci',   // ci: add github actions
                'chore',    // chore: update dependencies
                'revert'    // revert: revert changes
            ]
        ],
        'subject-case': [2, 'always', 'sentence-case']
    }
}
// for flexible commit messages
// module.exports = {
//     extends: ['@commitlint/cli', '@commitlint/config-conventional'],
//     rules: {
//         // Disable the type-enum rule
//         'type-enum': [0], // 0 disables the rule

//         // Disable the type-empty rule to allow commits without a type
//         'type-empty': [0], // 0 disables the rule

//         // Disable the subject-case rule
//         'subject-case': [0], // 0 disables the rule

//         // Optionally, disable subject-empty to allow empty subjects
//         'subject-empty': [0], // 0 disables the rule

//         // Disable other rules if needed
//     }
// }

5. Configure husky
To organize your Husky hooks, you can create a .husky folder for the pre-commit and commit-msg hooks. Here's how you can do it:

Create the .husky Folder
Run the following commands in your terminal:

mkdir .husky

Create Pre-commit Hook
Inside the .husky folder, create the pre-commit hook:

npx husky add .husky/pre-commit "npx lint-staged"

This command creates a .husky/pre-commit file with the following content:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

Create Commit-msg Hook
Inside the .husky folder, create the commit-msg hook:

npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

This command creates a .husky/commit-msg file with the following content:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit $1

5. Setup package.json

"scripts": {
    "dev": "nodemon server.js",
    "start": "node server.js",
    "prepare": "husky",
    "lint": "eslint",
    "lint:fix": "eslint --fix",
    "format:check": "prettier . --check",
    "format:fix": "prettier . --fix"
  },

 "devDependencies": {
    "@commitlint/cli": "^19.4.0",
    "@commitlint/config-conventional": "^19.2.2",
    "@eslint/js": "^9.9.1",
    "eslint": "^9.9.1",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.2.1",
    "globals": "^15.9.0",
    "prettier": "^3.3.3"
  }

Production level folder structure for a mern stack app in one command

Arshan Nawaz — Sat, 17 Aug 2024 13:30:14 +0000

*1. Client *

# Create folders
mkdir -p src/validations
mkdir -p src/components
mkdir -p src/utils
mkdir -p src/layouts src/routes src/pages/client/home src/pages/client/about src/pages/dashboard/home src/pages/dashboard/settings
mkdir -p src/redux/features/permission
mkdir -p src/redux/features/role
mkdir -p src/redux/features/loading
mkdir -p src/redux/features/auth
mkdir -p src/redux/middlewares
mkdir -p src/redux/actions

# Create files with path comments
echo "// src/validations/user.validation.js" > src/validations/user.validation.js

echo "// src/utils/formatDate.js" > src/utils/formatDate.js
echo "// src/utils/api.js" > src/utils/api.js
echo "// src/utils/EndPoints.js" > src/utils/EndPoints.js

echo "// src/layouts/ClientLayout.jsx" > src/layouts/ClientLayout.jsx
echo "// src/layouts/DashboardLayout.jsx" > src/layouts/DashboardLayout.jsx
echo "// src/routes/ClientRoutes.jsx" > src/routes/ClientRoutes.jsx
echo "// src/routes/DashboardRoutes.jsx" > src/routes/DashboardRoutes.jsx
echo "// src/routes/AppRouter.jsx" > src/routes/AppRouter.jsx

echo "// src/components/Button/Button.jsx" > src/components/Button/Button.jsx
echo "// src/pages/client/home/Home.jsx" > src/pages/client/home/Home.jsx
echo "// src/pages/client/about/About.jsx" > src/pages/client/about/About.jsx
echo "// src/pages/dashboard/home/DashboardHome.jsx" > src/pages/dashboard/home/DashboardHome.jsx
echo "// src/pages/dashboard/settings/Settings.jsx" > src/pages/dashboard/settings/Settings.jsx


echo "// src/redux/features/permission/permission.slice.js" > src/redux/features/permission/permission.slice.js
echo "// src/redux/features/role/role.slice.js" > src/redux/features/role/role.slice.js
echo "// src/redux/features/loading/loading.slice.js" > src/redux/features/loading/loading.slice.js
echo "// src/redux/features/permission/permission.service.js" > src/redux/features/permission/permission.service.js
echo "// src/redux/features/role/role.service.js" > src/redux/features/role/role.service.js
echo "// src/redux/features/auth/auth.slice.js" > src/redux/features/auth/auth.slice.js
echo "// src/redux/features/auth/auth.service.js" > src/redux/features/auth/auth.service.js
echo "// src/redux/store.js" > src/redux/store.js
echo "// src/redux/rootReducer.js" > src/redux/rootReducer.js
echo "// src/redux/actions/actionTypes.js" > src/redux/actions/actionTypes.js
echo "// src/redux/middlewares/loading.middleware.js" > src/redux/middlewares/loading.middleware.js

2. Server

# Create the main source folders
mkdir -p src/controllers
mkdir -p src/middlewares
mkdir -p src/models
mkdir -p src/routes
mkdir -p src/utils
mkdir -p src/config
mkdir -p src/validations
mkdir -p src/constants


# Create the public folder and profile folder
mkdir -p public/profile

# Create files with path comments in src/controllers
echo "// src/controllers/auth.controller.js: Controller for authentication-related routes" > src/controllers/auth.controller.js

# Create files with path comments in src/middlewares
echo "// src/middlewares/auth.middleware.js: Middleware for authentication" > src/middlewares/auth.middleware.js

# Create files with path comments in src/models
echo "// src/models/auth.model.js: Mongoose schema for authentication" > src/models/auth.model.js

# Create files with path comments in src/routes
echo "// src/routes/auth.route.js: Routes for authentication-related endpoints" > src/routes/auth.route.js

# Create files with path comments in src/utils
echo "// src/utils/example.util.js: Example utility function" > src/utils/example.util.js

# Create files with path comments in src/config
echo "// src/config/db.config.js: Configuration for database connection" > src/config/db.config.js
echo "// src/config/env.config.js: Configuration for environment variables" > src/config/env.config.js

# Create files with path comments in src/validations
echo "// src/validations/user.validation.js: Schema for user model" > src/validations/user.validation.js


# Create an example file in src/constants
echo "// src/constants/example.constants.js: Example constants file" > src/constants/example.constants.js

Centralized Loading State Management (Advanced) in react using redux toolkit

Arshan Nawaz — Sat, 17 Aug 2024 11:15:59 +0000

Setting up a Redux store with custom middleware and managing loading states across your app can be straightforward with a well-structured folder setup. Below is a step-by-step guide to organizing your Redux logic in a scalable and maintainable way.

1. src/redux/: Application Setup
**store.js:** This file is where you configure your Redux store, apply the middleware, and combine reducers.

// src/redux/store.js
import { configureStore } from '@reduxjs/toolkit';
import rootReducer from './rootReducer';
import loadingMiddleware from '../middleware/loading.middleware.js';

const store = configureStore({
  reducer: persistedReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: false, // Disable serializable checks for redux-persist
    }).concat(loadingMiddleware),
});

export default store;

rootReducer.js: Combines all the slices into a single root reducer.

import { combineReducers } from '@reduxjs/toolkit';
import loadingReducer from '../features/loading/loading.slice.js';
import dataAReducer from '../features/dataA/dataASlice';
import dataBReducer from '../features/dataB/dataBSlice';

const rootReducer = combineReducers({
  loading: loadingReducer,
  dataA: dataAReducer,
  dataB: dataBReducer,
});

export default rootReducer;

2. src/redux/features/: Feature-Specific Logic
Each feature of your application gets its own directory inside the features folder. This keeps your code modular and easier to maintain.

loading/: Handles loading states across the app.

loading.slice.js: Contains the slice for managing loading states.
loading.middleware.js: The middleware responsible for managing loading states based on async actions.

import { createSlice } from '@reduxjs/toolkit';

const initialState = {};

const loadingSlice = createSlice({
  name: 'loading',
  initialState,
  reducers: {
    setLoading: (state, action) => {
      const { key, value } = action.payload;
      state[key] = value;
    },
  },
});

export const { setLoading } = loadingSlice.actions;
export default loadingSlice.reducer;

// src/redux/middleware/loading.middleware.js
import { setLoading } from '../features/loading/loading.slice';

export const loadingMiddleware = (store) => (next) => (action) => {
  const { dispatch } = store;

  if (action.type.endsWith('/pending')) {
    dispatch(setLoading({ key: action.type.replace('/pending', ''), value: true }));
  } else if (action.type.endsWith('/fulfilled') || action.type.endsWith('/rejected')) {
    dispatch(setLoading({ key: action.type.replace(/\/(fulfilled|rejected)$/, ''), value: false }));
  }

  return next(action);
};

3. Example service/function

// dataAThunks.js
import { createAsyncThunk } from '@reduxjs/toolkit';

export const fetchDataA = createAsyncThunk('data/fetchDataA', async () => {
  const response = await fetch('/api/dataA');
  return response.json();
});

4. src/components/: UI Components
MyComponent.js: This component fetches and displays data from both fetchDataA and fetchDataB, using the loading states managed by the middleware.
fetchDataA and fetchDataB are the example functions for slices in async thunk or in redux

import React, { useEffect } from 'react';
import { useSelector, useDispatch } from 'react-redux';
import { fetchDataA } from '../features/dataA/dataAThunks';
import { fetchDataB } from '../features/dataB/dataBThunks';

const MyComponent = () => {
  const dispatch = useDispatch();
  const isLoadingFetchDataA = useSelector((state) => state.loading['data/fetchDataA']);
  const isLoadingFetchDataB = useSelector((state) => state.loading['data/fetchDataB']);

  useEffect(() => {
    dispatch(fetchDataA());
    dispatch(fetchDataB());
  }, [dispatch]);

  return (
    <div>
      {isLoadingFetchDataA ? (
        <p>Loading Data A...</p>
      ) : (
        <p>Data A Loaded!</p>
      )}

      {isLoadingFetchDataB ? (
        <p>Loading Data B...</p>
      ) : (
        <p>Data B Loaded!</p>
      )}
    </div>
  );
};

export default MyComponent;

5. src/index.js: Application Entry Point
The index.js file initializes your React application and provides the Redux store to the app.

import React from 'react';
import ReactDOM from 'react-dom';
import { Provider } from 'react-redux';
import App from './App';
import store from './app/store';

ReactDOM.render(
  <Provider store={store}>
    <App />
  </Provider>,
  document.getElementById('root')
);

6. (Optional)

you can me actionTypes to avoid spelling mistake etc when getting loading state of any service/function

// src/redux/actions/actionTypes.js

export const FetchDataA = 'data/fetchDataA';
export const FetchDataB = 'data/fetchDataB';

// And import in any component 
import { FetchDataA } from "../../../redux/actions/actionTypes";

 const isLoadinggetProjects = useSelector((state) => state.loading[FetchDataA]);

Summary:
This folder structure helps you keep your Redux logic, especially with multiple async actions and custom middleware, organized and maintainable. Each feature (like dataA and dataB) has its own slice and thunk files, and global state management tasks like loading states are centralized in a dedicated folder. This separation of concerns ensures that your application remains scalable as it grows.

Global Modal in react using redux toolkit

Arshan Nawaz — Fri, 16 Aug 2024 21:27:28 +0000

To build a global modal using Redux Toolkit where you can dynamically render different components based on a componentName passed to the modal, we'll break the process down into the following steps:

1. Create the Components Index File: This file will import all the components and export them as an object.
2. Set Up Redux Slice: This slice will handle the state of the modal, including whether it's open and which component should be rendered.
3. Create the Modal Component: This will be the global modal component that checks which component should be rendered based on the state.
4. Dispatching Modal Actions: You'll call these actions to open the modal and specify which component to render.

Step 1: Components Index File (components/Index.jsx)
This file will import all your components and export them as an object.

// components/Index.jsx
import ComponentA from './ComponentA';
import ComponentB from './ComponentB';
// Import all other components

const components = {
  ComponentA,
  ComponentB,
  // Add all other components
};

export default components;

Step 2: Redux Slice for Modal (features/modal/modalSlice.js)
This slice will handle opening and closing the modal, as well as tracking which component to render.

import { createSlice } from '@reduxjs/toolkit';

const initialState = {
  isOpen: false,
  componentName: null,
  componentProps: {},
};

const modalSlice = createSlice({
  name: 'modal',
  initialState,
  reducers: {
    openModal: (state, action) => {
      state.isOpen = true;
      state.componentName = action.payload.componentName;
      state.componentProps = action.payload.componentProps || {};
    },
    closeModal: (state) => {
      state.isOpen = false;
      state.componentName = null;
      state.componentProps = {};
    },
  },
});

export const { openModal, closeModal } = modalSlice.actions;

export default modalSlice.reducer;

Step 3: Global Modal Component (components/GlobalModal.jsx)
This component will check the current state and render the appropriate component from the components index.

// src/components/Modal/GlobalModal.jsx
import React from 'react';
import { useSelector, useDispatch } from 'react-redux';
import { FaTimes } from 'react-icons/fa'; // Importing the cross icon from react-icons
import components from '../Index';
import { closeModal } from '../../redux/features/modal/modal.slice';

const GlobalModal = () => {
  const dispatch = useDispatch();
  const modal = useSelector(state => state.modal);
  const { isOpen, componentName, componentProps } = modal;

  if (!isOpen || !componentName) return null;

  const ComponentToRender = components[componentName];

  return (
    <div className="fixed inset-0 flex items-center justify-center bg-black bg-opacity-50">
      <div className="bg-white p-6 rounded-lg relative shadow-lg">
        <button
          className="absolute top-2 right-2 text-gray-400 hover:text-gray-600"
          onClick={() => dispatch(closeModal())}
        >
          <FaTimes size={24} />
        </button>
        <ComponentToRender {...componentProps} />
      </div>
    </div>
  );
};

export default GlobalModal;

Step 4: Using the Modal in Your App
To open the modal and render a specific component, you would dispatch the openModal action from anywhere in your app.

import { useDispatch } from 'react-redux';
import { openModal } from './features/modal/modalSlice';

const SomeComponent = () => {
  const dispatch = useDispatch();

  const handleOpenModal = () => {
    dispatch(openModal({ componentName: 'ComponentA', componentProps: { someProp: 'value' } }));
  };

  return (
    <div>
      <button onClick={handleOpenModal}>Open Modal</button>
    </div>
  );
};

export default SomeComponent;

Integration
Finally, ensure your GlobalModal component is included in your app's root component so that it's always available.

import React from 'react';
import { Provider } from 'react-redux';
import store from './store';
import GlobalModal from './components/Modal/GlobalModal';
import SomeComponent from './SomeComponent';

const App = () => (
  <Provider store={store}>
    <SomeComponent />
    <GlobalModal />
  </Provider>
);

export default App;

To build a global modal using Redux Toolkit where you can dynamically render different components based on a componentName passed to the modal, we'll break the process down into the following steps:

2nd method => implementation with the onSave functionality and React.memo for optimizing re-renders.

Step 1: Components Index File (components/Index.jsx)
This file will import all your components and export them as an object.

// components/Index.jsx
import React from 'react';
import ComponentA from './ComponentA';
import ComponentB from './ComponentB';
// Import all other components

const components = {
  ComponentA: React.memo(ComponentA),
  ComponentB: React.memo(ComponentB),
  // Add all other components and memoize them
};

export default components;

Step 2: Redux Slice for Modal (features/modal/modalSlice.js)
This slice will handle opening and closing the modal and onSave, as well as tracking which component to render.
import { createSlice } from '@reduxjs/toolkit';

// features/modal/modalSlice.js
import { createSlice } from '@reduxjs/toolkit';

const initialState = {
  isOpen: false,
  componentName: null,
  componentProps: {},
  onSave: null, // Add onSave to the state
};

const modalSlice = createSlice({
  name: 'modal',
  initialState,
  reducers: {
    openModal: (state, action) => {
      if (!state.isOpen) {
        state.isOpen = true;
        state.componentName = action.payload.componentName;
        state.componentProps = action.payload.componentProps || {};
        state.onSave = action.payload.onSave || null;
      }
    },
    closeModal: (state) => {
      if (state.isOpen) {
        state.isOpen = false;
        state.componentName = null;
        state.componentProps = {};
        state.onSave = null; // Reset onSave when modal is closed
      }
    },
  },
});

export const { openModal, closeModal } = modalSlice.actions;

export default modalSlice.reducer;

Step 3: Global Modal Component (components/GlobalModal.jsx)
This component will check the current state ,onSave and render the appropriate component from the components index.

import React, { useCallback } from 'react';
import { useSelector, useDispatch } from 'react-redux';
import { closeModal } from '../features/modal/modalSlice';
import components from './Index';

// Selector to get the modal state
const selectModalState = (state) => ({
  isOpen: state.modal.isOpen,
  componentName: state.modal.componentName,
  componentProps: state.modal.componentProps,
  onSave: state.modal.onSave,
});

const GlobalModal = () => {
  const dispatch = useDispatch();
  const { isOpen, componentName, componentProps, onSave } = useSelector(selectModalState);

  if (!isOpen || !componentName) return null;

  const ComponentToRender = components[componentName];

  const handleSave = useCallback(() => {
    if (onSave) {
      onSave(componentProps); // Pass componentProps to the onSave callback
    }
    dispatch(closeModal()); // Optionally close the modal after saving
  }, [onSave, componentProps, dispatch]);

  return (
    <div className="fixed inset-0 flex items-center justify-center bg-black bg-opacity-50">
      <div className="bg-white p-4 rounded shadow-lg">
        <ComponentToRender {...componentProps} />
        <div className="mt-4 flex justify-end space-x-2">
          <button className="text-blue-500" onClick={handleSave}>
            Save
          </button>
          <button className="text-red-500" onClick={() => dispatch(closeModal())}>
            Close
          </button>
        </div>
      </div>
    </div>
  );
};

export default React.memo(GlobalModal);

Step 4: Opening the Modal with the Save Action
When you want to open the modal and use the onSave function, you do so as follows:

import React from 'react';
import { useDispatch } from 'react-redux';
import { openModal } from './features/modal/modalSlice';

const SomeComponent = () => {
  const dispatch = useDispatch();

  const handleOpenModal = () => {
    const onSave = (props) => {
      console.log('Saved with props:', props);
      // Perform your save logic here
    };

    dispatch(openModal({
      componentName: 'ComponentA',
      componentProps: { someProp: 'value' },
      onSave: onSave,
    }));
  };

  return (
    <div>
      <button onClick={handleOpenModal}>Open Modal</button>
    </div>
  );
};

export default React.memo(SomeComponent);

Integration
Finally, ensure your GlobalModal component is included in your app's root component so that it's always available.

import React from 'react';
import { Provider } from 'react-redux';
import store from './store';
import GlobalModal from './components/GlobalModal';
import SomeComponent from './SomeComponent';

const App = () => (
  <Provider store={store}>
    <SomeComponent />
    <GlobalModal />
  </Provider>
);

export default App;

Explanation

Components Index: This file maps all your components to their names, so you can render them dynamically.
Modal Slice: The slice manages the state of the modal, including which component to render and its props.
Global Modal: This component renders the appropriate component inside a modal based on the Redux state.
Usage: You can open the modal by dispatching the openModal action with the desired component name and props.

Download your Mern stack app Using scp (Secure Copy)

Arshan Nawaz — Tue, 21 May 2024 14:16:31 +0000

Step 1: Create Backup on Server
Connect to Your Server:
Use SSH to connect to your server. Replace and with your server's username and IP address.

ssh <remote-user>@<remote-ip>

Step 2: Create a Backup Directory (if not already created):
Create a directory to store your backups. For example, let's create a directory named backups in your home directory.

mkdir -p ~/backups

Step 3: Create the Backup:
Assuming your application files are in /var/www/websiteFolder/, create a backup of the portfolio directory.

tar -czvf ~/backups/app-backup-$(date +%F).tar.gz /var/www/portfolio/

Step 4: Download Backup to Local Machine
Open a New Terminal Window (on your local machine):
Open a new terminal window or tab on your local machine.

Download the Backup:
Use the scp command to download the backup file from the server to your local machine. Replace , , and accordingly.

scp <remote-user>@<remote-ip>:~/backups/app-backup-$(date +%F).tar.gz <local-path>

for Mac

mkdir -p /Users/username/backup
scp <remote-user>@<remote-ip>:~/backups/app-backup-$(date +%F).tar.gz /Users/username/backup
 app-backup-$(date +%F).tar.gz is file name. Also you can verify the name.

Step 5: Extract Backup file
Open terminal in /Users/username/backup and run command

tar -xzvf app-backup-2024-05-21.tar.g
 app-backup-2024-05-21.tar.g is file name, it can different in your case

How to create bitbucket CI/CD pipeline ( Node JS )

Arshan Nawaz — Wed, 13 Mar 2024 16:22:49 +0000

Step 1 — Logging in as root

ssh root@your_server_ip

Step 2 — Creating a New User

adduser sammy

Step 3 — Granting Administrative Privileges

usermod -aG sudo sammy

Step 4 — Setting Up a Firewall
If your domain is registered, then both OpenSSH and Nginx Full will run. Otherwise, only Nginx HTTP will run. In Nginx Full mode, both HTTP and HTTPS are available.

ufw app list


ufw allow OpenSSH


ufw enable


ufw status

Step 5 — Enabling External Access for Your Regular User
Configuring SSH access for your new user depends on whether your server’s root account uses a password or SSH keys for authentication.

If the root Account Uses SSH Key Authentication
If you logged in to your root account using SSH keys, then password authentication is disabled for SSH. To log in as your regular user with an SSH key, you must add a copy of your local public key to your new user’s ~/.ssh/authorized_keys file.
Since your public key is already in the root account’s ~/.ssh/authorized_keys file on the server, you can copy that file and directory structure to your new user account using your current session.
The simplest way to copy the files with the correct ownership and permissions is with the rsync command. This command will copy the root user’s .ssh directory, preserve the permissions, and modify the file owners, all in a single command. Make sure to change the highlighted portions of the command below to match your regular user’s name:

rsync --archive --chown=sammy:sammy ~/.ssh /home/sammy

Now, open up a new terminal session on your local machine, and use SSH with your new username:

ssh sammy@your_server_ip

You should be connected to your server with the new user account without using a password. Remember, if you need to run a command with administrative privileges, type sudo before the command like this:

sudo command_to_run

Step 6 — In your bitbucket
Go to repository setting and click on SSH keys, add your server ip address

Now fetch and then add host.
Step 7 — Copy publicKey
At same page of step 6 you can see generate ssh keys, click on it and copy public key

Step 8 — Paste public key to ~/.ssh/authorized_keys

sudo nano ~/.ssh/authorized_keys

Step 9 — Add SSH key to bitbucket from server
Run this command on server

cat ~/.ssh/id_rsa.pub

If it is present copy it otherwise generate ssh key and then again run this command.

ssh-keygen

After run this command again run

cat ~/.ssh/id_rsa.pub

Copy the ssh key and add it in ssh keys in bitbucket personal setting.

Step 10 — Change in /etc/ssh/sshd_config

sudo nano /etc/ssh/sshd_config

#PubkeyAuthentication yes                                                                                                                                                                   
PubkeyAcceptedKeyTypes=+ssh-rsa

Find both line if it is present then remove # from start.

Like

PubkeyAuthentication yes 
PubkeyAcceptedKeyTypes=+ssh-rsa

Otherwise add both lines.

Step 11 — Set remote origin ssh url

git remote set-url origin repo url

Step 12 — Create two files bitbucket-pipelines.yml and deploy.sh

bitbucket-pipelines.yml

pipelines:
  branches:
    staging:
      - step:
          script:
            - cat ./deploy.sh | ssh sammy@server-ip -T
            - echo "Deployment Completed"

deploy.sh

echo "Change project directory to: /var/www/project directory"
cd /var/www/project directory
# Pull the latest changes from the git repository
echo "Pulling latest changes from the git repo after resetting hard"
git reset --hard
git checkout staging
git pull origin staging
echo "installing package if new"
npm install
# Restart the Node.js app with PM2
pm2 stop server.js || true  # Ignore error if the app is not running
 # Start or restart the PM2-managed app
pm2 start server.js
# Restart Nginx
sudo systemctl restart nginx
echo 'Deployment finished on staging.'

Now enable and run your initial pipeline 🎉

How to create a bitbucket CI/CD pipeline ( React JS )

Arshan Nawaz — Wed, 13 Mar 2024 13:47:21 +0000