Subscriptions & Billing Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id] ================================================================================ SUBSCRIPTION PLANS APIs ================================================================================ -------------------------------------------------------------------------------- API: List Subscription Plans -------------------------------------------------------------------------------- GET /merchant/api/v1/subscription_plans Description: Retrieve all available subscription plans with pricing variants and features. Plans include pricing tiers (Daily, Monthly, Quarterly, Yearly) and feature lists. Headers: token: {{auth_token}} (Required) Response: 200 OK [ { "id": "671a151236ff2062807bdd2c", "name": "Uni-Connect", "description": "This is a professional plan providing advanced features.", "variants": [ { "id": "1", "mrp": 1700, "price": 1699, "currency": "INR", "duration": "Day" }, { "id": "2", "mrp": 5000, "price": 4587, "currency": "INR", "duration": "Quarterly" }, { "id": "3", "mrp": 15300, "price": 15291, "currency": "INR", "duration": "Yearly" } ], "features": [ "50GB Storage", "Priority Email Support", "Community Access", "Custom Reports" ], "created_at": "2024-10-24T09:36:18.664Z", "updated_at": "2024-10-24T09:36:18.664Z" } ] Flow Sequence: # Step 1: Gateway receives request GET /merchant/api/v1/subscription_plans [Seller API Gateway] # Step 2: Validate JWT Token POST /api/auth/token/verify [Auth Service] # Step 3: Fetch subscription plans from Account Service GET /api/subscription-plans [Account Service] # Step 4: Return plans with variants and features -------------------------------------------------------------------------------- API: Get Subscription Plan Features Comparison -------------------------------------------------------------------------------- GET /merchant/api/v1/subscription_plan_features Description: Retrieve detailed feature comparison across all subscription tiers (Community, Starter, Expert, Professional editions). Headers: token: {{auth_token}} (Optional - public access) Response: 200 OK [ { "id": "...", "feature_name": "Number of Custom Products", "community_edition": "100", "starter_edition": "1000", "expert_edition": "Unlimited", "professional_edition": "Unlimited", "highlight_feature": "New", "heading": "" }, ... ] Flow Sequence: # Step 1: Gateway receives request GET /merchant/api/v1/subscription_plan_features [Seller API Gateway] # Step 2: Fetch plan features from Account Service GET /api/subscription-plan-features [Account Service] # Step 3: Return feature comparison matrix ================================================================================ DOMAIN SUBSCRIPTION APIs ================================================================================ -------------------------------------------------------------------------------- API: Create Subscription -------------------------------------------------------------------------------- POST /merchant/api/v1/domains/:domain_id/subscriptions Description: Create a new subscription for a domain. Initiates payment processing if plan has a cost. Supports coupon codes for discounts. Path Parameters: domain_id: string (Required) - Domain identifier Headers: token: {{auth_token}} (Required) Request Body: { "plan_id": "67485f3a57b64d60e5953cf8", "variant_id": "2", "client_return_url": "https://your-domain.com/return", "coupon_code": "SUMMER25" } Response: 201 Created { "id": "671f7de7cdc8cb39ce0a03bb", "domain_id": "6704c8297084b0bec4f2873b", "plan_id": "671a151236ff2062807bdd2c", "session_id": "a745dfdd-454d-434c-b7a5-c385c8acdcfd", "status": "INACTIVE", "price": 4587, "start_date_time": "2025-01-28T12:04:55.828", "end_date_time": "2024-10-28T12:04:55.828", "billing_cycle": "MONTHLY", "billing_cycle_period": 1, "billing_cycle_period_unit": "DAY", "billing_cycle_start_date": "2024-10-28T12:04:55.828", "billing_cycle_end_date": "2025-01-28T12:04:55.828", "next_billing_date": "2025-01-28T12:04:55.828", "next_payment_date": "2025-01-28T12:04:55.828", "next_payment_amount": 4587, "next_payment_currency": "INR", "internal_billing": true, "internal_billing_ref_no": "INV1234567890", "internal_billing_note": "Monthly recurring charge for Standard Plan", "max_stores": 5, "grace_period": 5, "created_at": "2024-10-28T12:04:55.851Z", "updated_at": "2024-10-28T12:04:55.851Z" } Flow Sequence: # Step 1: Gateway receives request POST /merchant/api/v1/domains/:domain_id/subscriptions [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Validate plan and variant GET /api/subscription-plans/:plan_id [Account Service] # Step 4: Apply coupon if provided POST /api/coupons/apply [Coupon Service] # Step 5: Create subscription record POST /api/subscriptions [Account Service] # Step 6: If paid plan, initiate payment session POST /api/payments/create-session [Payment Service - JUSPAY/Stripe] # Step 7: Log subscription creation event POST /api/events/log [Util Service] # Step 8: Return subscription with payment redirect URL if applicable -------------------------------------------------------------------------------- API: List Subscriptions -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/subscriptions Description: Retrieve paginated list of all subscriptions for a domain, including historical and current subscriptions. Path Parameters: domain_id: string (Required) - Domain identifier Query Parameters: page: integer (Default: 0) - Page number size: integer (Default: 10) - Items per page order: string (Default: "desc") - Sort order (asc/desc) Headers: token: {{auth_token}} (Required) Response: 200 OK { "content": [ { "id": "672087e5d2e0d96d87da30a0", "domain_id": "670cb6487f2e38bf16eade44", "plan_id": "671a151236ff2062807bdd2c", "plan_name": "Uni-Connect", "channel": "STRIPE", "channel_id": "2", "status": "ACTIVE", "start_date": "2025-01-29T06:59:49.368", "end_date": "2024-10-29T06:59:49.368", "billing_cycle": "MONTHLY", "billing_cycle_period": 1, "next_billing_date": "2025-01-29T06:59:49.368", "next_payment_amount": 4587, "next_payment_currency": "INR", "max_stores": 5, "grace_period": 5, "created_at": "2024-10-29T06:59:49.389Z" } ], "pageable": { "page_number": 0, "page_size": 10, "sort": { "empty": true, "sorted": false, "unsorted": true }, "offset": 0 }, "total_pages": 1, "total_elements": 2, "first": true, "last": true } Flow Sequence: # Step 1: Gateway receives request GET /merchant/api/v1/domains/:domain_id/subscriptions [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Fetch subscriptions from Account Service GET /api/subscriptions?domain_id=:domain_id&page=:page&size=:size [Account Service] # Step 4: Return paginated subscription list -------------------------------------------------------------------------------- API: Get Active Subscription -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/subscriptions/active Description: Retrieve the currently active subscription for a domain. Returns subscription details with billing information. Path Parameters: domain_id: string (Required) - Domain identifier Headers: token: {{auth_token}} (Required) Response: 200 OK { "id": "671f7de7cdc8cb39ce0a03bb", "domain_id": "6704c8297084b0bec4f2873b", "plan_id": "671a151236ff2062807bdd2c", "plan_name": "Uni-Connect", "channel": "STRIPE", "channel_id": "2", "status": "ACTIVE", "start_date": "2025-01-28T12:04:55.828", "end_date": "2024-10-28T12:04:55.828", "billing_cycle": "MONTHLY", "billing_cycle_period": 1, "billing_cycle_period_unit": "DAY", "next_billing_date": "2025-01-28T12:04:55.828", "next_payment_date": "2025-01-28T12:04:55.828", "next_payment_amount": 4587, "next_payment_currency": "INR", "internal_billing": true, "internal_billing_ref_no": "INV1234567890", "max_stores": 5, "grace_period": 5, "created_at": "2024-10-28T12:04:55.851Z", "updated_at": "2024-10-28T12:05:07.142Z" } Flow Sequence: # Step 1: Gateway receives request GET /merchant/api/v1/domains/:domain_id/subscriptions/active [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Fetch active subscription GET /api/subscriptions/active?domain_id=:domain_id [Account Service] # Step 4: Return active subscription details -------------------------------------------------------------------------------- API: Get Subscription Transaction -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/subscriptions_transactions/:subscription_transactions_id Description: Retrieve details of a specific subscription transaction, including payment details, tax information, and billing cycle. Path Parameters: domain_id: string (Required) - Domain identifier subscription_transactions_id: string (Required) - Transaction ID Headers: token: {{auth_token}} (Required) Response: 200 OK { "id": "6784c17810110463d45723ed", "domain_id": "67597d67bdcd90444fce63da", "plan_id": "6748692ecbce973ea1b6c4eb", "variant_id": "1", "session_id": "6ba8623d-ee81-42f9-be40-fbb378cf1971", "status": "PENDING", "mrp": 8000, "price": 6999, "amount": 1259.82, "start_date_time": "2025-01-13T07:32:08.146", "end_date_time": "2025-02-13T07:32:08.146", "pg_order_id": "7fe96108-9105-4652-aaad-63df09c425fe", "billing_cycle_period": 1, "billing_cycle_period_unit": "MONTH", "next_billing_date": "2025-02-13T07:32:08.146", "internal_billing": true, "internal_billing_ref_no": "INV4296378894", "max_stores": 5, "grace_period": 5, "tax_type": "GST", "tax_currency": "INR", "tax_percentage": 18, "tax_inclusive": true, "tax": 18, "currency": "INR", "created_at": "2025-01-13T07:32:08.152Z" } Flow Sequence: # Step 1: Gateway receives request GET /merchant/api/v1/domains/:domain_id/subscriptions_transactions/:id [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Fetch transaction from Account Service GET /api/subscription-transactions/:id [Account Service] # Step 4: Return transaction details with tax info ================================================================================ SUBSCRIPTION LIFECYCLE MANAGEMENT APIs ================================================================================ -------------------------------------------------------------------------------- API: Pause Subscription -------------------------------------------------------------------------------- PUT /merchant/api/v1/domains/:domain_id/subscriptions/:subscription_id/pause Description: Pause an active subscription. The subscription status changes to PAUSED and billing is suspended until resumed. Path Parameters: domain_id: string (Required) - Domain identifier subscription_id: string (Required) - Subscription ID Headers: token: {{auth_token}} (Required) Response: 200 OK { "id": "67a465adc50fb2701994eea6", "domain_id": "67a465ac78ee87e330dad3e5", "plan_id": "67486c76f4f80a6f7d7d2ef3", "plan_name": "Trial", "status": "PAUSED", "paused_at": "2025-02-06T13:08:00.115", "billing_cycle_period": 30, "billing_cycle_period_unit": "DAY", "next_billing_date": "2025-03-08T07:33:01.668", "next_payment_amount": 0, "max_stores": 5, "grace_period": 5, "updated_at": "2025-02-06T13:08:00.145Z" } Flow Sequence: # Step 1: Gateway receives request PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/pause [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Update subscription status to PAUSED PUT /api/subscriptions/:id/pause [Account Service] # Step 4: Suspend billing schedules POST /api/billing/suspend [Billing Service] # Step 5: Log pause event POST /api/events/log [Util Service] # Step 6: Return updated subscription -------------------------------------------------------------------------------- API: Resume Subscription -------------------------------------------------------------------------------- PUT /merchant/api/v1/domains/:domain_id/subscriptions/:subscription_id/resume Description: Resume a paused subscription. The subscription status changes back to ACTIVE and billing resumes. Path Parameters: domain_id: string (Required) - Domain identifier subscription_id: string (Required) - Subscription ID Headers: token: {{auth_token}} (Required) Response: 200 OK { "id": "67a465adc50fb2701994eea6", "domain_id": "67a465ac78ee87e330dad3e5", "plan_id": "67486c76f4f80a6f7d7d2ef3", "plan_name": "Trial", "status": "ACTIVE", "paused_at": "2025-02-06T13:08:00.115", "next_billing_date": "2025-03-08T07:33:01.668", "next_payment_amount": 0, "max_stores": 5, "updated_at": "2025-02-06T13:08:48.452Z" } Flow Sequence: # Step 1: Gateway receives request PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/resume [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Update subscription status to ACTIVE PUT /api/subscriptions/:id/resume [Account Service] # Step 4: Resume billing schedules POST /api/billing/resume [Billing Service] # Step 5: Log resume event POST /api/events/log [Util Service] # Step 6: Return updated subscription -------------------------------------------------------------------------------- API: Cancel Subscription -------------------------------------------------------------------------------- PUT /merchant/api/v1/domains/:domain_id/subscriptions/:subscription_id/cancel Description: Cancel a subscription. The subscription status changes to CANCELLED and billing stops. This action may be irreversible. Path Parameters: domain_id: string (Required) - Domain identifier subscription_id: string (Required) - Subscription ID Headers: token: {{auth_token}} (Required) Response: 200 OK { "id": "67a465adc50fb2701994eea6", "domain_id": "67a465ac78ee87e330dad3e5", "plan_id": "67486c76f4f80a6f7d7d2ef3", "plan_name": "Trial", "status": "CANCELLED", "cancelled_at": "2025-02-06T13:07:36.885", "billing_cycle_period": 30, "billing_cycle_period_unit": "DAY", "next_payment_amount": 0, "max_stores": 5, "updated_at": "2025-02-06T13:07:36.928Z" } Flow Sequence: # Step 1: Gateway receives request PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/cancel [Seller API Gateway] # Step 2: Validate JWT Token and domain access POST /api/auth/token/verify [Auth Service] # Step 3: Update subscription status to CANCELLED PUT /api/subscriptions/:id/cancel [Account Service] # Step 4: Cancel billing schedules POST /api/billing/cancel [Billing Service] # Step 5: Adjust domain quotas and permissions POST /api/domains/:domain_id/quotas/reset [Account Service] # Step 6: Log cancellation event POST /api/events/log [Util Service] # Step 7: Send cancellation notification POST /api/notifications/send [Notification Service] # Step 8: Return updated subscription ================================================================================ SUBSCRIPTION STATUSES ================================================================================ Status Values: - INACTIVE: Subscription created but not yet activated (pending payment) - ACTIVE: Subscription is active and in good standing - PAUSED: Subscription temporarily paused by user - CANCELLED: Subscription has been cancelled - EXPIRED: Subscription period ended without renewal - PENDING: Payment pending for subscription activation Payment Channels: - STRIPE: Stripe payment gateway - CHARGEBEE: Chargebee billing platform - JUSPAY: JUSPAY payment gateway (India) Billing Cycle Units: - DAY: Daily billing - MONTH: Monthly billing - YEAR: Yearly billing ================================================================================ NOTES ================================================================================ 1. Subscription Plans: - Plans have multiple variants with different durations and pricing - Features are tied to plan tiers (Community, Starter, Expert, Professional) - Discounts applied: 10% for Quarterly, 25% for Yearly 2. Payment Processing: - Payment is processed via JUSPAY or Stripe - client_return_url is required for payment redirects - Tax (GST 18%) is applied based on configuration 3. Coupon Support: - Coupons can be applied during subscription creation - applicable_on: "SUBSCRIPTION" for subscription coupons - Discounts calculated on base price before tax 4. Grace Period: - Default grace period is 5 days after payment failure - Domain remains active during grace period - After grace period, domain features may be restricted 5. Store Limits: - max_stores defines the number of stores allowed - Typically 5 stores per subscription - Can be upgraded with plan changes