plans-api

Plans API

• Base Path: /api/v1/plans
• Auth: not required

Plan Model

• _id: string (ObjectId)
• points: number (Zish points provided)
• amount: number (price in baseCurrency)
• baseCurrency: string (e.g., USD, INR)
• country: string (ISO-like country code; e.g., US, IN)
• currencyCode: string (e.g., USD, INR)
• name: string (display name; optional)
• perks: string[] (bullet points; optional)
• currencySymbol: string (e.g., $, ₹; optional)
• highlight: boolean (mark as featured; default false)
• planType: 'SUBSCRIPTION' | 'TOPUP'
• billingPeriod: 'daily' | 'weekly' | 'monthly' | 'yearly' | null
• billingInterval: number | null (default 1)
• razorpayPlanId: string | null
• stripePriceId: string | null
• createdAt / updatedAt: string (ISO)

Example plan document:

{
  "_id": "66f00000000000000000abc1",
  "points": 100,
  "amount": 1.99,
  "baseCurrency": "USD",
  "country": "US",
  "currencyCode": "USD",
  "planType": "TOPUP",
  "billingPeriod": null,
  "billingInterval": 1,
  "razorpayPlanId": null,
  "stripePriceId": "price_123",
  "createdAt": "2025-09-01T10:00:00.000Z",
  "updatedAt": "2025-09-01T10:00:00.000Z"
}

List Plans

• Method: GET
• Path: /api/v1/plans
• Auth: not required
• Query:
  • country: string (optional; accepts country name/code or comma-separated list). Examples: IN, India, US, USA, United States, GB, UK.
    • If omitted or set to all, returns plans for all countries.
  • page: number (optional; default 1)
  • limit: number (optional; default 20, max 100)
  • count: boolean (optional; true to include total counts in meta)
• Behavior:
  • Filters by country when provided. Normalization rules:
    • India/IN → IN
    • USA/US/United States → US
    • UK/GB/United Kingdom → GB
    • Unrecognized short codes (<= 3 chars) are uppercased and used as-is.
    • all (any case) disables country filtering.
  • Pagination via page and limit. When count=true, returns totalCount and totalPages.
• Response 200:

{
  "data": [ { "_id": "66f...abc1", "points": 100, "country": "US", ... } ],
  "meta": { "page": 1, "limit": 20, "totalCount": 42, "totalPages": 3 }
}

• Errors:
  • 500: { "error": "Failed to fetch plans" }

Examples:

• All countries, default pagination:

  • GET /api/v1/plans

• Specific country (India):

  • GET /api/v1/plans?country=India

• Multiple countries (India + USA), with pagination and totals:

  • GET /api/v1/plans?country=India,USA&page=2&limit=10&count=true

Legacy

• Path: /api/plans
• Auth: not required
• Response 200: Array of plans (no meta).
• This legacy endpoint remains for backward compatibility; prefer /api/v1/plans for \{ data, meta \} shape and filtering.