# 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

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/subscription/change-quantity
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="157.69921875">Field</th><th width="162.7421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>quantity</code></td><td>Required</td><td>The new quantity value. Must be <strong>≥ 1</strong></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

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

{
    "subscriberId": "test@mail.com",
    "packageId": "zotlo.premium",
    "quantity": 2
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response <a href="#successful-response-example" id="successful-response-example"></a>

{% code overflow="wrap" %}

```json
{
  "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": "+905555555555",
      "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": "test@zotlo.com"
    }
  }
}
```

{% endcode %}

## Key **Response Fields** <a href="#key-response-fields" id="key-response-fields"></a>

<table data-header-hidden><thead><tr><th width="188.1640625">Field</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>The subscriber’s <em>operational</em> status (<code>active</code>, <code>grace</code>, <code>passive</code>).</td></tr><tr><td>realStatus</td><td>The <em>true</em> cancellation state. If a subscription is canceled (customer-initiated, merchant-initiated, or system-initiated), <strong>realStatus = passive immediately</strong>, even if <code>status</code> remains <code>active</code> until expire_date.</td></tr><tr><td>subscriptionType</td><td>Subscription period type: <code>trial</code> or <code>paid</code>.</td></tr><tr><td>startDate</td><td>Subscription start date.</td></tr><tr><td>expireDate</td><td>The end of the current billing cycle.</td></tr><tr><td>package</td><td>The package ID of the currently active package.</td></tr><tr><td>quantity</td><td>Represents the currently active and billable quantity for the package.</td></tr><tr><td>pendingQuantity</td><td>The new quantity that will apply at next renewal (only appears when decreasing quantity).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](https://docs.zotlo.com/integrating-zotlo/api-reference/error-handling))