Update Quantity

This endpoint allows merchants to update the billable quantity associated with a subscriber’s active package.

It is designed for seat-based, license-based, and similar pricing models where the total charge equals: unit price × quantity.

Use the POST method with this endpoint.

How Quantity Changes Work

Increasing Quantity (Upgrade)

If the new quantity is higher than the current one:

• An additional charge is attempted for the difference

• If the charge succeeds → quantity updates immediately

• If it fails → no change is applied

Decreasing Quantity (Downgrade)

If the new quantity is lower than the current one:

• Change is not applied immediately

• The updated quantity becomes active on the next renewal

• Until then, the current quantity continues to be billed

Method	POST
URL	https://api.zotlo.com/v1/subscription/change-quantity

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.
quantity	Required	The new quantity value. Must be ≥ 1

Sample Request

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

{
    "subscriberId": "[email protected]",
    "packageId": "zotlo.premium",
    "quantity": 2
}

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-5f354e9240c23",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "905555555555",
      "subscriptionType": "paid",
      "startDate": "2020-07-27 11:56:16",
      "expireDate": "2020-10-25 11:56:16",
      "package": "zotlo.premium",
      "country": "TR",
      "phoneNumber": "[phone]",
      "language": "tr",
      "originalTransactionId": "5a4d2db2-7be8-41e7-a6c8-63870762974b",
      "cancellation": null,
      "customParameters": null,
      "quantity": 19,
      "pendingQuantity": 17
    },
    "package": {
      "packageId": "zotlo.premium",
      "price": 49,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "customer": {
      "id": 7,
      "createDate": "2020-05-19 08:54:07",
      "country": "TR",
      "firstname": "Test",
      "lastname": "User",
      "email": "[email protected]"
    }
  }
}

Key Response Fields

status	The subscriber’s operational status (active, grace, passive).
realStatus	The true cancellation state. If a subscription is canceled (customer-initiated, merchant-initiated, or system-initiated), realStatus = passive immediately, even if status remains active until expire_date.
subscriptionType	Subscription period type: trial or paid.
startDate	Subscription start date.
expireDate	The end of the current billing cycle.
package	The package ID of the currently active package.
quantity	Represents the currently active and billable quantity for the package.
pendingQuantity	The new quantity that will apply at next renewal (only appears when decreasing quantity).

Failed Response

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