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.

Discount Behavior on Plan Change

• The unused value of remaining days is always calculated based on the actual amount paid by the customer. If the current subscription includes a discount, the discounted price is used.

• keepDiscount parameter can be used to preserve the existing discount during an upgrade or downgrade.

  • true → current discount continues if the target plan supports it.

• To apply a different discount, send discountCode . If a new discount is provided, the existing discount is overridden (only one discount can be active).

• Discount cycles (redemption count) increase only on renewal, not during plan changes.

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)
keepDiscount	Optional	Indicates whether the current discount should be preserved during the plan change. true → The existing discount is kept if the target plan supports it. false → The existing discount is not preserved.
discountCode	Optional	The code of the discount to apply during the plan change (e.g., NEWYEAR26). If provided, the existing discount (if any) will be overridden.
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",
  "saveCycle": "false", 
  "keepDiscount": "false"
}

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": "[email protected]",
            "subscriptionId": 20338,
            "subscriptionType": "trial",
            "startDate": "2026-03-12 13:44:12",
            "expireDate": "2026-03-19 13:44:12",
            "renewalDate": "2026-03-19 13:44:12",
            "package": "package_1",
            "country": "US",
            "phoneNumber": null,
            "language": "en",
            "originalTransactionId": "ffad490c-6681-5c76-f63000cafc46",
            "lastTransactionId": "ffad490c-6681-5c178-f63000cafc46",
            "subscriptionPackageType": "single",
            "cancellation": null,
            "customParameters": {
                "saveCycle": true,
                "subscriberIpAddress": "111111"
            },
            "quantity": 1,
            "pendingQuantity": 0,
            "renewalFetchCount": 0,
            "freezeEndDate": null
        },
        "package": {
            "packageId": "package_1",
            "price": 0,
            "currency": "USD",
            "packageType": "subscription",
            "name": "package_1",
            "subscriptionPackageType": "single",
            "bundlePackages": [],
            "discount": {
                "code": "DISC75NOTRIAL",
                "type": "rate",
                "appliedRate": 75,
                "appliedAmount": "9.6699999999999999289 USD"
            }
        },
        "customer": null,
        "newPackage": null,
        "card": {
            "cardNumber": "42424242****4242",
            "expireDate": "12/30",
        },
        "response": {
            "isSuccess": true,
            "transactionId": "ffad490c-61-5c76-a178-f63000cafc46",
            "providerTransactionId": "pi_3TA9WwCbenXbI1ZL1CrILgpO",
            "customTransactionId": "",
            "statusCode": "S0000001",
            "statusMessage": "Ödeme işlemi başarıyla tamamlandı.",
            "paymentDate": "2026-03-12 01:44:08",
            "providerStatus": "Captured",
            "paymentStatus": "COMPLETE",
            "redirectUrl": null,
            "packageId": "package_1",
            "providerPaymentMethod": null,
            "networkDeclineCode": null,
            "networkDeclineMessage": null
        },
        "redirect": null,
        "paymentStatus": "COMPLETE",
        "paymentHash": "83f89c204fef73a34e4a04eb38f06f477f0",
        "oldOriginalTransactionId": "95271196-8438-d7637a100802"
    }
}

Key Response Fields

Field	Description
profile	Updated subscription profile after the change
package	Details of the new package and discount
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)