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.

Method	POST
URL	https://api.zotlo.com/v1/subscription/cancellation

Request Parameters

Field	Type	Description
subscriberId	Required	The email or phone number the user provided when starting the subscription.
packageId	Required	The ID of the current active package. A successful response is returned only if the user has a subscription for this package.
cancellationReason	Required	Free-text reason for the subscription cancellation. Shown in the profile under cancellation.reason.
force	Optional	Controls when the cancellation takes effect: 1 → The subscription is terminated immediately. any other value or omitted → The subscriber can continue using the service until the end of the current billing period.

Sample Request

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

{
  "subscriberId": "[email protected]",
  "cancellationReason": "Not Interest",
  "force": 0,
  "packageId": "zotlo-premium"
}

You can find your AccessKey and AccessSecret in the Zotlo Panel under Developer Tools → API Keys

Sending ApplicationId is optional.

Successful Response

{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32a93a80310",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "passive",
      "subscriberId": "[email protected]",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 21:57:25",
      "expireDate": "2020-09-09 21:57:25",
      "package": "zotlo-premium",
      "country": "TR",
      "phoneNumber": "[phone]",
      "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": "[email protected]"
    }
  }
}

Key Response Fields

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

Failed Response

All failed responses follow the same standard error format. (See: Error Handling)