---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/subscription/api/cancel/index.md
description: >-
  The Cancel Subscription API terminates an existing subscription plan,
  supporting immediate cancellation or cancellation at the end of the current
  billing period.
---
# Cancel Subscription

```apidef
endpoint: POST /v4/subscriptions/cancel
name: Cancel Subscription
summary: Cancel a subscription plan
tags: Subscription, Management
```

The Cancel Subscription API terminates an existing subscription plan, supporting immediate cancellation or cancellation at the end of the current billing period.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ merchantSubscriptionId | string | C | Merchant-defined unique subscription plan ID. At least one of this field or subscriptionId is required. |
| └─ subscriptionId | string | C | PingPong subscription ID. At least one of this field or merchantSubscriptionId is required. |
| └─ requestId | string | M | Merchant request ID. |
| └─ cancelAtPeriodEnd | boolean | O | If true is passed, the subscription will not be canceled immediately and will instead be canceled automatically at the end of the current billing cycle. Before the period ends, the subscription remains active in its current state and the merchant should continue providing service. If false is passed, the cancellation is handled immediately according to this request or other change parameters. Default is false . |
| └─ prorationMode | string | O | Proration mode for immediate cancellation. Only applicable when cancelAtPeriodEnd is false . Defaults to NONE if not provided, meaning no automatic refund is calculated based on the remaining period. Valid values include: PRORATED : considers the residual value of the unused service time and calculates any extra charge or refund based on the remaining time.; NONE : does not consider the residual value of the unused service time.; CUSTOM : the merchant defines the refund amount generated by this cancellation instead of letting the system calculate the refund amount based on the remaining cycle automatically.; Note: when cancelAtPeriodEnd is true (period-end cancellation), this field together with customRefundAmount , customCurrency , and refundNotifyUrl must all be omitted — even explicitly passing NONE is rejected with 102000 refund fields only support immediate cancellation . For period-end cancellation, omit the prorationMode field entirely. |
| └─ customRefundAmount | string | C | Required when prorationMode is CUSTOM . Indicates the merchant-defined refund amount for this cancellation. This amount is used only for the refund handling associated with this cancellation request. |
| └─ customCurrency | string | C | Required when prorationMode is CUSTOM . Indicates the currency corresponding to the merchant-defined refund amount. Use a 3-letter ISO 4217 currency code. |
| └─ refundNotifyUrl | string | O | If this cancellation generates a refund, this URL is used to receive the asynchronous notification for that refund result. It applies only to this cancellation request.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications. |

### Request Example

```json
{
  "clientId": "2024061100000000001",
  "accId": "20240611000000000010001",
  "signType": "SHA256",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_M_202606110001\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"requestId\":\"REQ_SUB_CANCEL_001\",\"cancelAtPeriodEnd\":false,\"prorationMode\":\"CUSTOM\",\"customRefundAmount\":\"0.33\",\"customCurrency\":\"USD\",\"refundNotifyUrl\":\"https://merchant.example.com/refund/notify\"}"
}
```

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ merchantSubscriptionId | string | Merchant-defined unique subscription plan ID. |
| └─ subscriptionId | string | PingPong subscription ID. |
| └─ requestId | string | Merchant request ID. |
| └─ status | string | Subscription plan status. Valid values include: PENDING : the subscription has been created but is not yet active.; IN_TRIAL : the subscription is in the trial period and service is available, but the first formal charge has not completed yet.; ACTIVE : the subscription is currently active and the user is entitled to the service.; PAST_DUE : the subscription reached its charge time but the current charge failed, entering the dunning or retry stage.; CANCELLED : the subscription has ended and will not renew automatically.; |
| └─ cancelReason | string | Returned when the subscription status is CANCELLED , indicating why the subscription ended. user_requested : canceled by the user; merchant_requested : canceled by the merchant; payment_retry_exhausted : retry attempts exhausted; plan_ended : plan naturally ended; |
| └─ notifyUrl | string | Subscription notification URL. |
| └─ startAt | string | Subscription start time as a 13-digit millisecond timestamp string. |
| └─ endAt | string | Subscription end time as a 13-digit millisecond timestamp string. |
| └─ period | object | Subscription billing cycle. |
| └─ └─ count | integer | Number of units in one formal billing cycle. Must be at least 1 . For example, unit = MONTH and count = 1 means monthly billing. This is not the total number of billing cycles. |
| └─ └─ unit | string | Subscription period unit type. Valid values include: YEAR : the subscription cycle is measured in years.; MONTH : the subscription cycle is measured in months.; WEEK : the subscription cycle is measured in weeks.; DAY : the subscription cycle is measured in days.; |
| └─ flatPrice | object | Recurring amount and currency for each formal billing cycle. |
| └─ └─ amount | string | Recurring billing amount for each cycle. |
| └─ └─ currency | string | Recurring billing currency in ISO 4217 3-letter format. |
| └─ totalPeriodCount | integer | Total number of formal billing cycles in the subscription plan. Must be at least 1 and excludes the trial period. If omitted, the number of formal billing cycles is unlimited. |
| └─ trial | object | Trial settings. |
| └─ └─ startAt | string | Trial start time as a 10-digit second-level timestamp string. |
| └─ └─ endAt | string | Trial end time as a 10-digit second-level timestamp string. |
| └─ └─ periodDays | integer | Trial duration in days. |
| └─ autoRecovery | object | Automatic retry settings. |
| └─ └─ enabled | boolean | Whether automatic retry is enabled. Automatic retry is enabled by default. true : retry enabled; false : retry disabled; |
| └─ cancelAtPeriodEnd | boolean | Whether the subscription plan will be canceled at the end of the current billing cycle. true means it will be canceled at period end. |
| └─ cancelAt | string | Actual cancellation time as a 13-digit millisecond timestamp string. |
| └─ resultCode | string | Business result code. |
| └─ resultMessage | string | Business result message. |

### Response Example

```json
{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_MER_001\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"requestId\":\"REQ_SUB_CANCEL_001\",\"status\":\"CANCELLED\",\"cancelReason\":\"merchant_requested\",\"notifyUrl\":\"https://merchant.example.com/notify/subscription\",\"startAt\":\"1792152473588\",\"endAt\":\"1823688473588\",\"flatPrice\":{\"amount\":\"10.00\",\"currency\":\"USD\"},\"period\":{\"count\":1,\"unit\":\"MONTH\"},\"totalPeriodCount\":12,\"trial\":{\"startAt\":\"1785152760\",\"endAt\":\"1785757560\",\"periodDays\":7},\"autoRecovery\":{\"enabled\":true},\"cancelAtPeriodEnd\":false,\"cancelAt\":\"1792152491606\",\"resultCode\":\"000000\",\"resultMessage\":\"SUCCESS\"}",
  "code": "000000",
  "description": "SUCCESS"
}
```