# Change Detail & Prorate Preview

The Change Detail API is used to preview the proration breakdown before initiating a change, including old/new plan comparison, remaining value proration, diff amount, and effective time. This API does not perform an actual change; it only computes and returns preview data for the merchant system to display.

# Merchant Preview API

API

Request API: /api/subscription/change/detail

Request Method: POST

Request Type: application/json or application/x-www-form-urlencoded

# Request Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant No	mchNo	Yes	String(30)	M1621873433953	Merchant Number
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Subscription ID	subscriptionId	Yes	String(32)	SUB_20210618164232	Subscription ID
Target Plan ID	newPlanId	No	String(32)	PLAN_002	Target subscription plan ID; mutually exclusive with newPlanCode
Target Plan Code	newPlanCode	No	String(64)	PRO_MONTH	Target subscription plan code; mutually exclusive with newPlanId
Change Type	changeType	Yes	String(20)	UPGRADE	Change type: UPGRADE / DOWNGRADE
Effective Type	effectiveType	Yes	String(20)	IMMEDIATE	Effective type: IMMEDIATE / NEXT_PERIOD
Request Time	reqTime	Yes	long	1622016572190	Request timestamp (13 digits)
API Version	version	Yes	String(3)	1.0	API version, fixed: 1.0
Sign	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value, see signature algorithm
Sign Type	signType	Yes	String(32)	MD5	Signature type, currently only supports MD5

# Request Example Data

{
  "mchNo": "M1623984572",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "subscriptionId": "SUB_20210618164232",
  "newPlanId": "PLAN_002",
  "changeType": "UPGRADE",
  "effectiveType": "IMMEDIATE",
  "reqTime": "1622016572190",
  "version": "1.0",
  "signType": "MD5",
  "sign": "84F606FA25A6EC4783BECC08D4FDC681"
}

Target Plan Parameter

Provide either newPlanId or newPlanCode. The example uses newPlanId; merchants may instead pass newPlanCode (e.g. "newPlanCode": "PRO_MONTH") to identify the target plan — the system resolves it to the corresponding planId using the subscription's mchNo/appId/currency.

# Response Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Return State	code	Yes	int	0	0-Success, others-Error, see error codes
Return Msg	msg	No	String(128)	Signature failed	Specific error reason
Sign Info	sign	No	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	Signature for data
Return Data	data	No	Object	{}	Returned change detail data

# Data Format (SubscriptionChangeDetailRS)

Field Name	Variable Name	Type	Example Value	Description
Subscription ID	subscriptionId	String	SUB_20210618164232	Subscription ID
Subject	subject	String	Membership Subscription	Subscription product name
Old Plan ID	oldPlanId	String	PLAN_001	Original subscription plan ID
Old Plan Name	oldPlanName	String	Basic Monthly	Original subscription plan name
Old Plan Code	oldPlanCode	String	BASIC_MONTH	Original subscription plan code
Old Plan Interval Unit	oldPlanIntervalUnit	String	MONTH	Original plan interval unit: DAY/WEEK/MONTH/YEAR
Old Plan Interval Count	oldPlanIntervalCount	Integer	1	Original plan interval count
Old Plan Amount	oldAmount	Long	1000	Original plan current amount, in cents
New Plan ID	newPlanId	String	PLAN_002	New subscription plan ID
New Plan Name	newPlanName	String	Pro Monthly	New subscription plan name
New Plan Code	newPlanCode	String	PRO_MONTH	New subscription plan code
New Plan Interval Unit	newPlanIntervalUnit	String	MONTH	New plan interval unit: DAY/WEEK/MONTH/YEAR
New Plan Interval Count	newPlanIntervalCount	Integer	1	New plan interval count
New Plan Amount	newAmount	Long	2500	New plan current amount, in cents
Change Type	changeType	String	UPGRADE	UPGRADE / DOWNGRADE
Effective Type	effectiveType	String	IMMEDIATE	IMMEDIATE / NEXT_PERIOD
Effective Time	effectiveTime	Date	1622016572190	Estimated effective timestamp
Remaining Value	remainingValue	Long	600	Prorated remaining value of current period, in cents
Diff Amount	diffAmount	Long	1500	Difference in cents, positive means supplement required
Prorate Days Used	prorateDaysUsed	Integer	12	Days used in current period
Prorate Days Total	prorateDaysTotal	Integer	30	Total days in current period
Currency	currency	String	USD	Currency
Trial Skipped	trialSkipped	Boolean	false	Whether the new plan trial period was skipped (true if trial already used)

# Response Example Data

{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "subscriptionId": "SUB_20210618164232",
    "subject": "Membership Subscription",
    "oldPlanId": "PLAN_001",
    "oldPlanName": "Basic Monthly",
    "oldPlanCode": "BASIC_MONTH",
    "oldPlanIntervalUnit": "MONTH",
    "oldPlanIntervalCount": 1,
    "oldAmount": 1000,
    "newPlanId": "PLAN_002",
    "newPlanName": "Pro Monthly",
    "newPlanCode": "PRO_MONTH",
    "newPlanIntervalUnit": "MONTH",
    "newPlanIntervalCount": 1,
    "newAmount": 2500,
    "changeType": "UPGRADE",
    "effectiveType": "IMMEDIATE",
    "effectiveTime": 1622016572190,
    "remainingValue": 600,
    "diffAmount": 1500,
    "prorateDaysUsed": 12,
    "prorateDaysTotal": 30,
    "currency": "USD",
    "trialSkipped": false
  },
  "sign": "F4DA202C516D1F33A12F1E547C5004FD"
}

# Proration Rules

Proration

Remaining Value Proration: For immediate changes, the system prorates the remaining value of the original plan based on days used in the current period, to offset the new plan cost.
Diff Calculation: diffAmount = new plan current amount - prorated remaining value. A positive diff requires a user supplement payment; a zero or negative diff requires no supplement.
Trial Skipped: If the user has already enjoyed a subscription trial period, switching to a new plan with a trial period will skip the trial and bill at the standard rate (trialSkipped=true).

← Create Change Request Cancel Change Reservation →