Seller Orchestra Internal API Mapping

Subscriptions & Billing

Subscription plans, billing management, and payment processing for seller services

3-Layer Architecture

Seller API Gateway Seller Admin (Orchestra Layer) Account / Billing Service (Core Microservices)

Subscription Lifecycle States

INACTIVE → ACTIVE → PAUSED ↔ ACTIVE → CANCELLED

Additional states: PENDING (payment processing), EXPIRED (end of term)

1 Subscription Plans APIs

List Subscription Plans

Get all available subscription plans with pricing tiers

GET
GET /merchant/api/v1/subscription_plans Gateway
GET /api/subscription_plans Seller Admin

Returns plans with variants: Day, Monthly, Quarterly, Yearly

1 GET /api/subscription-plans Account Service

Get Subscription Plan Features

Compare features across different subscription plans

GET
GET /merchant/api/v1/subscription_plan_features Gateway
GET /api/subscription_plan_features Seller Admin

Returns feature matrix: max_stores, limits per plan tier

1 GET /api/subscription-plan-features Account Service

2 Domain Subscription APIs

Create Subscription

Subscribe a domain to a plan with payment processing

POST
POST /merchant/api/v1/domains/:domain_id/subscriptions Gateway
POST /api/subscriptions Seller Admin

Request Body:

{
  "plan_variant_id": "uuid",
  "coupon_code": "DISCOUNT20",
  "payment_channel": "JUSPAY"
}
1 GET /api/subscription-plans/:plan_variant_id Account Service
2 POST /api/coupons/validate Coupon Service
3 POST /api/payments/initiate Payment Service (JUSPAY/Stripe)
4 POST /api/subscriptions Account Service
5 POST /api/billing/schedule Billing Service

List Domain Subscriptions

Get paginated list of all subscriptions for a domain

GET
GET /merchant/api/v1/domains/:domain_id/subscriptions Gateway
Query params: page, size, sort
GET /api/subscriptions?domain_id=:domain_id Seller Admin

Returns paginated response with content[], pageable, totalPages

1 GET /api/subscriptions?domain_id=:domain_id&page=0&size=20 Account Service

Get Active Subscription

Get the currently active subscription for a domain

GET
GET /merchant/api/v1/domains/:domain_id/subscriptions/active Gateway
GET /api/subscriptions/active?domain_id=:domain_id Seller Admin

Returns subscription with plan details, billing info, next_billing_date

1 GET /api/subscriptions/active?domain_id=:domain_id Account Service
2 GET /api/subscription-plans/:plan_id Account Service

Get Subscription Transaction

Get payment transaction details for a subscription

GET
GET /merchant/api/v1/domains/:domain_id/subscriptions_transactions/:id Gateway
GET /api/subscriptions_transactions/:id Seller Admin

Returns transaction with amount, status, payment_channel, invoice details

1 GET /api/subscription-transactions/:id Billing Service
2 GET /api/payments/:payment_id Payment Service

3 Subscription Lifecycle Management

Pause Subscription

Temporarily pause an active subscription

PUT
PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/pause Gateway
PUT /api/subscriptions/:id/pause Seller Admin

Status: ACTIVE → PAUSED | Billing cycles suspended

1 GET /api/subscriptions/:id Account Service
2 PUT /api/subscriptions/:id/status Account Service
3 PUT /api/billing/schedule/:id/pause Billing Service
4 POST /api/notifications/subscription-paused Notification Service

Resume Subscription

Resume a paused subscription

PUT
PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/resume Gateway
PUT /api/subscriptions/:id/resume Seller Admin

Status: PAUSED → ACTIVE | Billing cycles resumed

1 GET /api/subscriptions/:id Account Service
2 PUT /api/subscriptions/:id/status Account Service
3 PUT /api/billing/schedule/:id/resume Billing Service
4 POST /api/notifications/subscription-resumed Notification Service

Cancel Subscription

Permanently cancel an active or paused subscription

PUT
PUT /merchant/api/v1/domains/:domain_id/subscriptions/:id/cancel Gateway
PUT /api/subscriptions/:id/cancel Seller Admin

Status: ACTIVE/PAUSED → CANCELLED | Irreversible action

1 GET /api/subscriptions/:id Account Service
2 PUT /api/subscriptions/:id/status Account Service
3 DELETE /api/billing/schedule/:id Billing Service
4 POST /api/payments/cancel-recurring Payment Service
5 POST /api/notifications/subscription-cancelled Notification Service

Documentation Notes

1

Plan Variants: Each plan has multiple variants (Day, Monthly, Quarterly, Yearly) with different pricing tiers

2

Payment Channels: JUSPAY, STRIPE, CHARGEBEE supported for payment processing

3

Grace Period: 5 days default grace period for failed payment recovery

4

Tax Handling: GST 18% applied, tax_inclusive flag determines pricing display

5

Store Limits: max_stores (default 5) enforced per subscription plan

Open full text mapping