Subscription update

2026-05-18 10:10

The subscription plan update feature provides buyers with a flexible way to manage their subscriptions. Depending on their actual needs, buyers can upgrade or downgrade plans, end the current subscription period early, postpone the end time, or update details such as the subscription description at any time.

This feature is not restricted by a fixed billing cycle, every change takes effect immediately, allowing buyers to instantly enjoy the features and benefits of their new plan. By flexibly adjusting subscription content, buyers can meet their needs at different stages, continuously enjoy the best user experience, and ensure that functions and services always align with their actual requirements.

Use the update API to complete subscription updates. You can modify your subscription from the following dimensions.

Note: When a periodic payment is being processed, if the update API is called at the same time to modify the subscription, the system will return the UPDATE_FORBIDDEN_DURING_PAYMENT error. After receiving this error code, it is recommended to retry the API call later.

Subscription description update

Note: This operation only updates the subscription description information and does not change the subscription amount, currency, or subscription period .

To update the subscription description, please provide the following parameters:

Parameter	Required	Description
subscriptionId	Yes	The original subscription ID
subscriptionUpdateRequestId	Yes	The unique ID assigned by a merchant to identify a subscription update request.
subscriptionDescription	No	The subscription description to be updated.

Request example for reference:

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313",

    "subscriptionDescription": "Description update",

    "subscriptionId": "202603131900000000000000E0000115288"

    }

Subscription upgrade

To upgrade the subscription plan, please provide the following parameters:

Parameter	Required	Description
subscriptionId	Yes	The original subscription ID
subscriptionUpdateRequestId	Yes	The unique ID assigned by a merchant to identify a subscription update request.
paymentAmount	No	The payment amount for each period, used for the deduction request in the next period.
prorationSettings.customAmount	No	The difference amount, used to make up the price difference.
prorationSettings.prorationMode	No	Price difference mode. In the subscription upgrade scenario, set the value to `IMMEDIATE_PAY_CUSTOM_AMOUNT`.
orderInfo	No	Subscription order information, used for Antom internal risk control and billing display only. Not involved in actual payment processing.

The following example illustrates the key timestamps and parameter sources when a buyer upgrades from a Standard Monthly membership ($30) to a Premium Monthly membership ($50).

Note: The API for creating a subscription depends on the payment method used. Details are as follows:
APM integration: Call create to create a subscription.
Card, Apple Pay and Google Pay integration: Call pay (One-time Payments) to create a subscription.
Payment Element integration: Call createPaymentSession (One-time Payments) to create a subscription.

Subscription information before upgrade	Sample	Parameter resource
Before upgrade	Standard Monthly membership ($30)	N/A
Billing sycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Subscription start time	2026-03-13T18:15:29+08:00	The value of subscriptionStartTime passed during creation.
Time and amount of the first subscription charge	2026-03-13T18:15:29+08:00 Deduct the current subscription fee of $30.	Return through the asynchronous notification of the first subscription charge.
Start time of the second billing cycle	2026-04-13T18:15:29+08:00	Return through the asynchronous notification of the second subscription charge.
Time and amount of the second subscription charge	2026-04-12T18:20:29+08:00 Deduct the current subscription fee of $30.	Return through the asynchronous notification of the second subscription charge.

Subscription information after upgrade	Sample	Parameter resource
After upgrade	Premium Monthly membership ($50)	N/A
Billing sycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Upgrade trigger time	2026.04.20T19:00:00+08:00	The time when the update API call succeeds.
Time and amount of the charge	2026.04.20T19:02:00+08:00 Deduct the subscription price difference of $20.	Return through the asynchronous notification of the second subscription charge.
Start time of the third billing cycle	2026-05-13T18:15:29+08:00	Return through the asynchronous notification of the third subscription charge.
Time and amount of the third subscription charge	2026.05.12T18:20:29+08:00 Deduct the current subscription fee of $50.	Return through the asynchronous notification of the third subscription charge.

Request example for reference:

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20250925_002",
    "paymentAmount": {
        "currency": "USD",
        "value": "5000"
    },
    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Premium monthly Membership",
    "subscriptionId": "202603131900000000000000E0000115608",
    "orderInfo": {
        "orderAmount": {
            "currency": "USD",
            "value": "5000"
        }
    },
    "prorationSettings": {
        "prorationMode": "IMMEDIATE_PAY_CUSTOM_AMOUNT",
        "customAmount": {
            "currency": "USD",
            "value": "2000"
        }
    }
}

Subscription downgrade

To dgrade the subscription plan, please provide the following parameters:

Parameter	Required	Description
subscriptionId	Yes	The original subscription ID
subscriptionUpdateRequestId	Yes	The unique ID assigned by a merchant to identify a subscription update request.
paymentAmount	No	The payment amount for each period, used for the deduction request in the next period.
prorationSettings.customAmount	No	The difference amount, used to make up the price difference.
prorationSettings.prorationMode	No	Price difference mode. In the subscription upgrade scenario, set the value to `IMMEDIATE_REFUND_CUSTOM_AMOUNT`.
orderInfo	No	Subscription order information, used for Antom internal risk control and billing display only. Not involved in actual payment processing.

The following example illustrates the key timestamps and parameter sources when a buyer downpgrades from a Premium Monthly membership ($50) to a Standard Monthly membership ($30).

Note: The API for creating a subscription depends on the payment method used. Details are as follows:
APM integration: Call create to create a subscription.
Card, Apple Pay and Google Pay integration: Call pay (One-time Payments) to create a subscription.
Payment Element integration: Call createPaymentSession (One-time Payments) to create a subscription.

Subscription information before downgrade	Sample	Parameter resource
Before downgrade	Premium Monthly membership ($50)	N/A
Billing sycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Subscription start time	2025-09-25T18:15:29+08:00	The value of subscriptionStartTime passed during creation.
Time and amount of the first subscription charge	2025-09-25T18:15:29+08:00 Deduct the current subscription fee of $50.	Return through the asynchronous notification of the first subscription charge.
Start time of the second billing cycle	2025-10-25T18:15:29+08:00	Return through the asynchronous notification of the second subscription charge.
Time and amount of the second subscription charge	2025-10-24T18:20:29+08:00 Deduct the current subscription fee of $50.	Return through the asynchronous notification of the second subscription charge.

Subscription information after downgrade	Sample	Parameter resource
After downgrade	Premium Monthly membership ($50)	N/A
Billing sycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Downgrade trigger time	2025.10.30T19:00:00+08:00	The time when the update API call succeeds.
Refund time and amount	2025.10.30T19:02:00+08:00 Refund the subscription price difference of $20.	Return through the asynchronous notification of the second subscription charge.
Start time of the third billing cycle	2025-11-25T18:15:29+08:00	Return through the asynchronous notification of the third subscription charge.
Time and amount of the third subscription charge	22025.11.24T18:20:29+08:00 Deduct the current subscription fee of $30.	Return through the asynchronous notification of the third subscription charge.

Request example for reference:

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313_002",
    "paymentAmount": {
        "currency": "USD",
        "value": "3000"
    },
    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Normal monthly Membership",
    "subscriptionId": "202603131900000000000004E0000002358",
    "orderInfo": {
        "orderAmount": {
            "currency": "USD",
            "value": "3000"
        }
    },
"prorationSettings": {
        "prorationMode": "IMMEDIATE_REFUND_CUSTOM_AMOUNT",
        "customAmount": {
            "currency": "USD",
            "value": "2000"
        }
    }
}

Period change

To change the subscription period type, please provide the following parameters:

Parameter	Required	Description
subscriptionId	Yes	The original subscription ID
subscriptionUpdateRequestId	Yes	The unique ID assigned by a merchant to identify a subscription update request.
periodRule.periodType	No	Period type, currently supports four types: `YEAR`, `MONTH`, `WEEK`, and `DAY`.
periodRule.periodCount	No	Period interval, defines a complete subscription period together with the periodType parameter.

The following example illustrates the key timestamps and parameter sources before and after the subscription period change.

Note: The API for creating a subscription depends on the payment method used. Details are as follows:
APM integration: Call create to create a subscription.
Card, Apple Pay and Google Pay integration: Call pay (One-time Payments) to create a subscription.
Payment Element integration: Call createPaymentSession (One-time Payments) to create a subscription.

Subscription information before change	Sample	Parameter resource
Before change	Weekly membership	N/A
Billing cycle	Weekly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"WEEK"}`).
Subscription start time	2026-03-16T08:18:54+08:00	The value of subscriptionStartTime passed during creation.
Time of the first subscription charge	2026-03-16T08:18:54+08:00	Return through the asynchronous notification of the first subscription charge.
Start time of the second billing cycle	2026-03-23T08:18:54+08:00	Return through the asynchronous notification of the first subscription charge.

Subscription information after change	Sample	Parameter resource
After change	Monthly membership	N/A
Billing cycle	Monthly	The period information provided in the update API (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Subscription period change trigger time	2026-03-24T12:18:54+08:00	The time when the update API call succeeds.
Start time of the third billing cycle	2026-03-30T08:18:54+08:00	Return through the asynchronous notification of the third subscription charge.
Start time of the fourth billing cycle	2026-04-30T08:18:54+08:00	Return through the asynchronous notification of the fourth subscription charge.

Request example for reference:

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20250316_001",

    "periodRule": {
        "periodType": "MONTH",
        "periodCount": 1
    },
    "subscriptionDescription": "Premium monthly Membership (change period)",
    "subscriptionId": "202603161900000000000000E0000117794"


}

Subscription period adjustment

To modify the subscription period (e.g., early termination or postponement), please provide the following parameters:

Parameter	Required	Description
subscriptionId	Yes	The original subscription ID
subscriptionUpdateRequestId	Yes	The unique ID assigned by a merchant to identify a subscription update request.
nextSubscriptionDate	No	Next subscription start time. The value of this parameter should be derived based on the corresponding advance or delay duration.

Note: nextSubscriptionDate must be earlier than the current time + periodCount*periodType.

The following example illustrates the key timestamps and parameter sources for ending the current subscription early.

Note: The API for creating a subscription depends on the payment method used. Details are as follows:
APM integration: Call create to create a subscription.
Card, Apple Pay and Google Pay integration: Call pay (One-time Payments) to create a subscription.
Payment Element integration: Call createPaymentSession (One-time Payments) to create a subscription.

Subscription information before adjustment	Sample	Parameter resource
Before adjustment	Monthly membership	N/A
Billing cycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Subscription start time	2026-03-13T16:00:29+08:00	The value of subscriptionStartTime passed during creation.
Time of the first subscription charge	2025-03-13T16:00:29+08:00	Return through the asynchronous notification of the first subscription charge.
Start time of the second billing cycle	2025-04-13T16:00:29+08:00 (Before adjustment)	Return through the asynchronous notification of the second subscription charge.

Subscription information after adjustment	Sample	Parameter resource
After adjustment	Monthly membership	N/A
Billing cycle	Monthly	The period information provided during creation (`"periodRule":{"periodCount":1,"periodType":"MONTH"}`).
Adjustment trigger time	2026-03-20T19:00:00+08:00	The time when the update API is called with the nextSubscriptionDate parameter set to `2026-04-10T00:00:02+08:00`.
Start time of the second billing cycle	2026-04-10T00:00:02+08:00	Return through the asynchronous notification of the second subscription charge.
Start time of the third billing cycle	2026-05-10T00:00:02+08:00	Return through the asynchronous notification of the second subscription charge.

Request example for reference:

copy
{
    "subscriptionUpdateRequestId": "subscription_update_20260313_007",


    "subscriptionDescription": "Advance the current subscription end date",
    "subscriptionId": "202603131900000000000000E0000117414",
  "nextSubscriptionDate": "2026-04-10T00:00:02+08:00"

}