update

2026-04-22 07:42

POST /v1/subscriptions/update

Call this API to update an existing subscription, such as upgrading or downgrading the subscription, updating the subscription description, changing the subscription period type, or adjusting the subscription period.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

subscriptionUpdateRequestId String REQUIRED

The unique ID assigned by a merchant to identify a subscription update request.

More information:

This field is an API idempotency field.
Maximum length: 64 characters

subscriptionId String REQUIRED

The unique ID assigned by Antom to identify a subscription.

More information:

Maximum length: 64 characters

subscriptionDescription String

The description of the subscription, used for displaying user consumption records and other actions.

Note: Specify this parameter when you need to update the subscription description.

More information:

Maximum length: 256 characters

periodRule PeriodRule

The subscription period rule, used to define a subscription's billing period.

Note: Specify this parameter when you need to change the subscription period type.

Show child parameters

paymentAmount Amount

The payment amount charged to the user per subscription period.

Note: Specify this parameter when you need to upgrade or downgrade the subscription.

Show child parameters

subscriptionEndTime Datetime

The date and time when the subscription ends.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

orderInfo OrderInfo

The order information of the subscription. This field is used for different purposes:

During the payment process, this field is mainly used by Antom for risk control or anti-money laundering.
After the payment is completed, this field is used for recording and reporting purposes such as purchase tracking and regulatory reporting.

Note: Specify this parameter when you need to upgrade or downgrade the subscription.

Show child parameters

prorationSettings ProrationSettings

The rules and methods for price difference handling.

Note: Specify this parameter when there is a price difference that needs to be handled.

Show child parameters

nextSubscriptionDate Datetime

The next billing date specified by the merchant.

Note: Since subscription renewals begin attempting to process the payment 24 hours before the scheduled billing time, the specified next billing date must be at least 24 hours from the current time. If the specified next billing date is less than 24 hours from the current time, the subscription upgrade will fail and return a PROCESS_FAIL error code.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

Response parameters

result Result REQUIRED

Indicates whether this API is called successfully.

Show child parameters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Method

POST

Request Body

Response

Response Body

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success.	The interface is called successfully.
UPDATE_FORBIDDEN_DURING_PAYMENT	F	Update is forbidden during payment.	Try again in a while. If error persists, contact Antom Technical Support.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.	Contact Antom Technical Support for detailed reasons.
PAYMENT_COUNT_EXCEED_LIMIT	F	The maximum number of payments exceeds the limit that is specified by the payment method.	Contact Antom Technical Support for specific limitations.
REPEAT_REQ_INCONSISTENT	F	The amount or currency is different from the previous request.	Ensure all the parameters in the requests are the same or use a new paymentRequestId to initiate the payment again.
PAYMENT_IN_PROCESS	F	The payment is being processed.	Contact Antom Technical Support for detailed reasons.
USER_AMOUNT_EXCEED_LIMIT	F	Payment amount exceeds user's amount limit.	Create a new request by using an amount less than or equal to the account's available balance, or contact Antom Technical Support.
RISK_REJECT	F	The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.	If the user does not receive the refund within two weeks, contact Antom Technical Support.
USER_NOT_EXIST	F	The user not exist.	Contact Antom Technical Support for detailed reasons.
ORDER_NOT_EXIST	F	The order doesn't exist.	Check whether paymentId is correct.
ACCESS_DENIED	F	Access is denied.	Contact Antom Technical Support for detailed reasons.
CLIENT_FORBIDDEN_ACCESS_API	F	The client is not authorized to use this API.	Contact Antom Technical Support for detailed reasons.
INVALID_API	F	The called API is invalid or not active.	Contact Antom Technical Support to resolve the issue.
PARAM_ILLEGAL	F	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.
INVALID_SIGNATURE	F	The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard.	Check whether the private key used to sign a request matches the public key of Antom Dashboard. The following signature references are useful: The signature field in a request header How to calculate a signature
OAUTH_FAILED	F	OAuth process failed.	Contact Antom Technical Support for detailed reasons.
KEY_NOT_FOUND	F	The private key or public key of Antom or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue.
SYSTEM_ERROR	F	A system error occurred.	Contact Antom Technical Support for detailed reasons.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Antom Technical Support if failed to call the registration interface.
UNKNOWN_CLIENT	F	The client is unknown.	Contact Antom Technical Support for detailed reasons.