# Cancel Subscription

This endpoint to cancels a subscriber's active subscription. You can either cancel **at the end of the current billing period** or **immediately**, depending on the `force` parameter.

Use the **POST** method to query a subscriber. Both **subscriberId** and **packageId** parameters are required to retrieve the correct subscription record.

The response includes the subscription’s state, status, lifecycle dates, and related metadata.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/subscription/cancellation
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>cancellationReason</code></td><td>Required</td><td>Free-text reason for the subscription cancellation. Shown in the profile under <code>cancellation.reason</code>.</td></tr><tr><td><code>force</code> </td><td>Optional</td><td><p>Controls when the cancellation takes effect:</p><ul><li><code>1</code> → The subscription is terminated immediately.</li><li>any other value or omitted → The subscriber can continue using the service until the end of the current billing period.</li></ul></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/subscription/cancellation HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en

{
  "subscriberId": "test@mail.com",
  "cancellationReason": "Not Interest",
  "force": 0,
  "packageId": "zotlo-premium"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32a93a80310",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "passive",
      "subscriberId": "test@mail.com",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 21:57:25",
      "expireDate": "2020-09-09 21:57:25",
      "package": "zotlo-premium",
      "country": "TR",
      "phoneNumber": "+905555555555",
      "language": "tr",
      "originalTransactionId": "80397a95-742d-4c74-975e-f740d1909580",
      "cancellation": {
        "date": "2020-08-11 14:20:42",
        "reason": "Not Interest",
        "code": "CU00001"
      },
      "customParameters": {
        "source": "Landing"
      }
    },
    "package": {
      "packageId": "zotlo-premium",
      "price": 3.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "newPackage": null,
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "test@test.com"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="205.5546875">Field</th><th>Description</th></tr></thead><tbody><tr><td>profile.status</td><td>high-level subscription status delivered to your app. <code>active</code>, <code>grace</code>, High-level status of the subscription (<code>active</code>, <code>grace</code>, <code>passive</code>).</td></tr><tr><td>profile.realStatus</td><td><p>Internal status that immediately reflects cancellation.</p><ul><li><code>passive</code> → subscription is considered canceled by Zotlo, even if <code>status</code> may stay <code>active</code> until <code>expireDate</code> in some legacy flows.</li></ul></td></tr><tr><td>profile.subscriptionType</td><td><code>trial</code> → subscription is in trial period<br><code>paid</code> → subscription has been charged at least once</td></tr><tr><td>startDate / expireDate</td><td>Subscription start and current period end dates.</td></tr><tr><td>cancellation</td><td><p>Contains details if the subscription was canceled:</p><ul><li><code>cancellation.date</code> – cancellation timestamp</li><li><code>cancellation.reason</code> – human-readable reason</li><li><code>cancellation.code</code> – cancellation code (<code>CP00001</code>, <code>CU00001</code>, <code>CU00002</code>, etc.)</li></ul></td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](https://docs.zotlo.com/integrating-zotlo/api-reference/error-handling))