# cancel

> Use this API to cancel or terminate a subscription. Canceling a subscription means that the service is not provided to the user after the current subscription period ends, and terminating a subscription means the service ceases immediately.

`POST /v1/subscriptions/cancel`

Use this API to cancel or terminate a subscription. Canceling a subscription means that the service is not provided to the user after the current subscription period ends, and terminating a subscription means the service ceases immediately. 

# 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

#### subscriptionId (String)

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.

> Note: Specify at least one of _subscriptionId_ and _subscriptionRequestId_. A one-to-one correspondence between _paymentId_ and _paymentRequestId_ exists.

More information:

- Maximum length: 64 characters

#### subscriptionRequestId (String)

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

> Note: Specify at least one of _subscriptionId_ and _subscriptionRequestId_. A one-to-one correspondence between _paymentId_ and _paymentRequestId_ exists.

More information:

- Maximum length: 64 characters

#### cancellationType (String, REQUIRED)

The cancellation type for the subscription. Valid values are:

-   `CANCEL`: indicates canceling the subscription. The subscription service is not provided to the user after the current subscription period ends.
-   `TERMINATE`: indicates terminating the subscription. The subscription service is ceased immediately.

More information:

- Maximum length: 32 characters

## Response parameters

#### result (Result, REQUIRED)

Indicates whether this API is called successfully. If this API is successfully called, the subscription is canceled successfully.

##### resultCode (String, REQUIRED)

The result code. The result code that might be returned 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 the subscription was canceled successfully.
-   `F`: indicates that the subscription failed to be canceled.
-   `U`: indicates that the cancellation result 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 interface is called successfully. |
| 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. |
| 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. |
| 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. |

## Request

### CANCEL_SUBSCRIPTION

```json
{
  "subscriptionId": "20221215190000000000000040000",
  "cancellationType": "CANCEL"
}
```

### TERMINATE_SUBSCRIPTION

```json
{
  "subscriptionId": "2022102519000000000000019000000",
  "cancellationType": "TERMINATE"
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
```