Change Plan

This endpoint allows you to replace a subscriber’s current package with a new one (upgrade or downgrade). Plan transitions follow Zotlo’s billing logic, including prorated upgrades, cycle preservation options, and deferred downgrades.

The service operates using the POST method.

How Plan Changes Work

Upgrade

When switching to a more expensive plan, Zotlo processes the change based on the saveCycle parameter.

If saveCycle = true (Keep Billing Cycle)

• The current billing cycle does not change, expireDate remains the same.

• The unused portion of the current plan is credited.

• The user pays only the price difference.

• The new plan becomes active immediately after a successful charge.

• If the charge fails → upgrade does not happen; current plan continues.

If saveCycle = false (Start New Cycle)

• The current billing cycle is terminated immediately.

• The unused amount is credited to the new plan.

• A full charge for the new plan is attempted instantly.

• A new billing cycle starts immediately with a new expire date.

• If the charge fails → upgrade does not occur; the current plan continues unchanged.

Note: Choosing saveCycle = false is ideal when you want users to “reset” into a new full cycle.

Downgrade

When switching to a cheaper plan:

• The change never happens immediately.

• The new plan activates at the next renewal.

• The current billing cycle continues uninterrupted.

• expireDate does not change.

• No proration or credit calculation applies.

Note: saveCycle is ignored for downgrades because downgrades always activate at the next renewal.

You can learn more about plan changes 👉 here

Currency Matching Rule

The new plan must use the same currency defined for the subscriber’s country. Example: A subscriber using USD in the USA can only switch to another USD plan.

Method	POST
URL	https://api.zotlo.com/v1/payment/change-package

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.
newPackageId	Required	Package ID to switch to
changeType	Required	upgrade or downgrade
saveCycle	Required	true → Upgrade with cycle continuity false → Upgrade with a new billing cycle (This parameter has no effect for downgrades)
subscriberIpAddress	Required	Subscriber’s IP address
redirectUrl	Optional	Required for 3DS flows, user is redirected here after authentication
platform	Optional	Example: web, ios, android

Sample Request

POST https://api.zotlo.com/v1/payment/change-package HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••

{
  "platform": "web",
  "subscriberId": "Z113322",
  "subscriberIpAddress": "212.154.57.216",
  "redirectUrl": "https://example.com",
  "changeType": "upgrade",
  "packageId": "zotlo.premium",
  "newPackageId": "zotlo.business"
}

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-5f32ad6851343",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "7",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 12:55:23",
      "expireDate": "2020-09-10 14:38:34",
      "package": "zotlo-business",
      "country": "TR",
      "phoneNumber": "[phone]",
      "language": "tr",
      "originalTransactionId": "79448a13-b8bf-4b9e-9666-5dbabd8992c2",
      "cancellation": null,
      "customParameters": {
        "source": "Landing"
      }
    },
    "package": {
      "packageId": "zotlo-business",
      "price": 9.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Business"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "[email protected]"
    },
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "response": {
      "isSuccess": true,
      "transactionId": "79448a13-b8bf-4b9e-9666-5dbabd8992c2",
      "statusCode": "S0000001",
      "paymentStatus": "COMPLETE"
    }
  }
}

Key Response Fields

Field	Description
profile	Updated subscription profile after the change
package	Details of the new package
response.isSuccess	Indicates whether any required payment was successful
card	Card information used for upgrade
expireDate	Updated expire date (only changes for successful upgrades)

Failed Response

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