Quantity Update

Manage quantity with Zotlo

This feature allows merchants to update the billable quantity associated with a package. It is designed for pricing models where the total charge is based on a countable quantity, such as seat-based, license-based sales models.

Common use cases include SaaS products charging per seat, license bundles, or packages where the total price is calculated as unit price × quantity.

Rules for Quantity Changes

If the new value is higher than the current quantity, an additional charge for the increased quantity is attempted until the end of the current renewal period. If the payment is successful, the quantity is updated immediately.

If the new value is lower than the current quantity, the update is not applied immediately. The updated quantity will take effect in the next renewal period.

Method	POST
URL	https://api.zotlo.com/v1/subscription/change-quantity
Request Parameters	subscriberId: The email or phone number used by the user when starting the subscription. packageId: The unique identifier of the package whose unit quantity will be updated. quantity: Represents the new unit quantity for the package. The value must be at least 1.

Example Request

To send a request to the Transaction Report Service, you must include your Access Key, Access Secret, and App ID in the request headers. You can obtain these credentials from the Zotlo Panel → Developer Tools → API Keys section.

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
}

Successful Response Examples

{
  "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"
    },
    "newPackage": null,
    "card": null,
    "customer": {
      "id": 7,
      "createDate": "2020-05-19 08:54:07",
      "country": "TR",
      "firstname": "Test",
      "lastname": "User",
      "email": "[email protected]"
    }
  }
}

Successful Response Parameters

The parameters included in the successful response are as follows.

Field	Description
status	Indicates the subscription status. active : User can continue to use their rights. passive : User's rights have expired. grace : The package renewal process could not be completed, but the user can continue to use their rights for a certain period.
realStatus	Provides the real status of the subscriber. Returns 'passive' if the user's account has been cancelled in any way. Different from 'status', 'active' will continue to return until the user's expiration date. active : User can continue to use their rights. passive : User's account has been cancelled in some way.Different from 'status'. 'Status' will continue to return active until the user's expiration date.
subscriptionType	Indicates the status of the user's subscription. trial : The subscriber is still within the trial period. paid : The user has transitioned to paid period and has been charged at least once for the package.
startDate	Start date of the subscription.
expireDate	Expire date of the subscription. Renewal will be made on this date.
package	Package information for the active subscription.
country	Country information of the user.
language	Language information of the user.
quantity	Represents the currently active and billable quantity for the package.
pendingQuantity	Represents the planned quantity that will become effective in the next renewal period. If the newly submitted quantity value is lower than the current one, the update is not applied immediately and the updated quantity is stored in the pending.quantity field. The specified value will be automatically activated in the next renewal period.

Failed Response Example

Our services return HTTP status code 200 for successful responses. For unsuccessful cases, HTTP status codes 400 or 500 are returned. An example error response is as follows:

{
  "meta": {
    "requestId": "app2.domain-REQ-5e73a811d5d",
    "httpStatus": 400,
    "errorMessage": "Kullanıcı profili bulunamadı.",
    "errorCode": 400009
  },
  "result": []
}

Failed Response Parameters

Below are the parameters included in failed responses.

Field	Description
requestId	A unique request parameter generated and stored by Zotlo.
httpStatus	The HTTP status code associated with the response. Standard codes include 400 or 500.
errorMessage	Details of the error received. Error messages are sent according to the language parameter you send. 404001: Invalid endpoint 401002: AccessKey, AccessSecret parameters are incorrect. 400008: SubscriberId parameter is incorrect. 400009: Subscriber profile not found. 500000: Server error.
errorCode	The error code specific to Zotlo. Zotlo has unique error codes for each type of error. 404001: Invalid endpoint 401002: AccessKey, AccessSecret parameters are incorrect. 400008: SubscriberId parameter is incorrect. 400009: Subscriber profile not found. 500000: Server error.
result	This field can dynamically change. In case of an error, the response from the service may be returned filled with details or as an empty object.