# change > Antom uses this API to send the payment result of each subscription period to the merchant when the payment reaches a final state of success or failure. `POST /v1/subscriptions/change` Use this API to change the subscription information, such as the subscription period rule, the payment amount for each subscription period, or other information. Subscription information can only be changed for subscriptions that have not been canceled or terminated. # Structure A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：  - [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur) - [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90) > **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 #### subscriptionChangeRequestId (String, REQUIRED) The unique ID assigned by a merchant to identify a subscription change request. Antom uses this field for idempotency control. > **Note**: For subscription change requests that are initiated with the same value of _subscriptionChangeRequestId_ and reach a final status of `S` or`F`, the same result is to be returned for the 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. The value of this parameter is the value of the same parameter that is returned by [**notifyPayment**](https://docs.antom.com/ac/ams/notify_subpayment.md) and [**notifySubscription**](https://docs.antom.com/ac/ams/notify_sub.md) for the original 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 if you want to change this information. More information: - Maximum length: 256 characters #### subscriptionStartTime (Datetime) The date and time when the subscription becomes active. > **Note**: Specify this parameter when you want to designate the start time of the changed subscription. If you leave this parameter empty, the default value of this parameter is the time when Antom receives this request. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". #### subscriptionEndTime (Datetime) The date and time when the subscription ends. The default value of this parameter is `2099-12-31T23:59:59+08:00`. > **Note**: Specify this parameter when you want to change this information. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". #### periodRule (PeriodRule) The subscription period rule, used to define a subscription's billing period. > **Note**: Specify this parameter if you want to change this information. ##### periodType (String, REQUIRED) The subscription period type. Valid values are: - `YEAR`: indicates that the subscription period is measured in years.  - `MONTH`: indicates that the subscription period is measured in months.  - `WEEK`: indicates that the subscription period is measured in weeks.  - `DAY`: indicates that the subscription period is measured in days. More information: - Maximum length: 20 characters ##### periodCount (Integer, REQUIRED) The number of period types within one subscription period. For example, if the value of _periodType_ is `MONTH` and the value of _periodCount_ is `2`, it means that the subscription period is two months. More information: - Value range: 1 - unlimited #### subscriptionExpiryTime (Datetime) A specific date and time after which the created subscription expires. When the subscription expires, the order must be terminated. The default value of this parameter is 30 minutes after the subscription creation request is sent. > **Note**: Specify this parameter if you want to change the subscription creation expiration time. The specified payment expiration time must be less than 48 hours after the subscription request is sent. More information: - The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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 if you want to change this information. ##### orderAmount (Amount, REQUIRED) The order amount of the merchant that directly provides services or goods to the customer. The value of this parameter is displayed on user consumption records or the payment result page. ###### currency (String, REQUIRED) The transaction currency that is specified in the contract. A 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ###### value (Integer, REQUIRED) The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a 0-decimal currency). > **Note**: For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe). More information: - Value range: 1 - unlimited #### paymentAmount (Amount) The payment amount charged to the user per subscription period. > **Note**: Specify this parameter if you want to change this information. ##### currency (String, REQUIRED) The transaction currency, which is a 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a positive integer in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to `100`; or if the currency is JPY and the amount is ￥1, set the value of this parameter to `1`. For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe). For details about the minimum payment amount allowed for each payment method, see [Minimum amount rules](https://docs.antom.com/ac/ref/cc.md#q9R5A). > **Note**: Due to the currency practices in Indonesia, when the currency is IDR, round the amount with Banker's Rounding and fix the last two digits of this parameter as `00`. More information: - Value range: 1 - unlimited #### paymentAmountDifference (Amount) The payment amount for the initial subscription period after changing the payment amount for subsequent subscription periods. > **Note**: Specify this parameter if you change the payment amount for each subscription period. ##### currency (String, REQUIRED) The transaction currency, which is a 3-letter currency code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. More information: - Maximum length: 3 characters ##### value (Integer, REQUIRED) The value of the amount as a positive integer in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to `100`; or if the currency is JPY and the amount is ￥1, set the value of this parameter to `1`. For details about the smallest currency unit, see [Smallest unit of the currency](https://docs.antom.com/ac/ref/cc.md#ONkIe). For details about the minimum payment amount allowed for each payment method, see [Minimum amount rules](https://docs.antom.com/ac/ref/cc.md#q9R5A). > **Note**: Due to the currency practices in Indonesia, when the currency is IDR, round the amount with Banker's Rounding and fix the last two digits of this parameter as `00`. More information: - Value range: 1 - unlimited ## Response parameters #### result (Result, REQUIRED) Indicates whether this API is called successfully. > **Note**: This field does not indicate the subscription change result. Antom notifies you of the subscription change result through [**notifySubscription**](https://docs.antom.com/ac/ams/notify_sub.md). ##### resultCode (String, REQUIRED) The result code. Possible values are listed in the **Result/Error** codes table on this page. More information: - Maximum length: 64 characters ##### resultStatus (String, REQUIRED) The result status. Valid values are: - `S`: indicates that this API is called successfully. - `F`: indicates that this API call is failed. - `U`: indicates that the API call status is unknown. ##### resultMessage (String, REQUIRED) Result message that explains the result code. More information: - Maximum length: 256 characters ## Result/Error codes | Code | Value | Message | Further action | | --- | --- | --- | --- | | SUCCESS | S | Success | The API is called successfully. | | 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. | | INVALID_CLIENT_STATUS | F | The client status is invalid. | Contact Antom Technical Support for detailed reasons. | | 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 | | 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. | | MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration API. Contact Antom Technical Support if failed to call the registration API. | | OAUTH_FAILED | F | OAuth process failed. | Contact Antom Technical Support for detailed reasons. | | 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. | | PAYMENT_NOT_QUALIFIED | F | The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Tokenized Payment, or is forbidden to make a payment. | Contact Antom Technical Support for detailed reasons. | | 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. | | 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. | | UNKNOWN_CLIENT | F | The client is unknown. | Contact Antom Technical Support for detailed reasons. | | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the API 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 API again to resolve the issue. If not resolved, contact Antom Technical Support. | ## Request ```json { "subscriptionChangeRequestId": "amsmdsubscription_change_20221207_143228_641", "paymentAmountDifference": { "currency": "PHP", "value": "100" }, "paymentAmount": { "currency": "PHP", "value": "200" }, "periodRule": { "periodType": "MONTH", "periodCount": 6 }, "subscriptionDescription": "subscriptiondesc_change_20221207_143228_641", "subscriptionEndTime": "2023-12-07T14:32:28+08:00", "subscriptionId": "20221207190000000000000050000004531", "orderInfo": { "orderAmount": { "currency": "PHP", "value": "200" } }, "subscriptionStartTime": "2022-12-07T14:32:28+08:00" } ``` ## Response ```json { "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ```