# Add usage

Use the **addSubscriptionUsage** method in SOAP API 6.0 to add multiple usages at the same time.

## Request parameters

| Parameters                | Type     | Required | Description                                                                                                                                                                                                                |
| ------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **merchantCode**          | String   | Required | The system-generated merchant ID.                                                                                                                                                                                          |
| **sessionID**             | String   | Required | Unique 2Checkout session ID code.                                                                                                                                                                                          |
| **SubscriptionReference** | String   | Required | Unique 2Checkout subscription reference code.                                                                                                                                                                              |
| **hash**                  | String   | Required | The MD5 hmac key for the request.                                                                                                                                                                                          |
| **OptionCode**            | String   | Required | Unique 2Checkout option code.                                                                                                                                                                                              |
| **UsageStart**            | Datetime | Required | Date when the usage starts. Format "YYYY-MM-DD". The timezone used is the one on the server.                                                                                                                               |
| **UsageEnd**              | Datetime | Required | Date when the usage ends. Format "YYYY-MM-DD". The timezone used is the one on the server.                                                                                                                                 |
| **Units**                 | Number   | Required | Number of usage units consumed by user.                                                                                                                                                                                    |
| **Description**           | String   | Optional | It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September. |

### Request sample

```php
<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = "B7D8E72224";

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->OptionCode = "scale";
    $subscriptionUsageRequest->UsageStart = "2025-03-02 10:00:10";
    $subscriptionUsageRequest->UsageEnd = "2025-04-01 10:00:10";
    $subscriptionUsageRequest->Units = 404;
    $response = $client->addSubscriptionUsage(
        $sessionID,
        $SubscriptionReference,
        [$subscriptionUsageRequest]
    );
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}
 exit;
```

## Response

The successful **addSubscriptionUsage** call via SOAP APIv6 returns the [Usage](https://verifone.cloud/docs/2checkout/API-Integration/JSON-RPC_API_6.0/API-Requests/Usage-management/) object.

```php
array(1) {
      [0] =>
      class stdClass#3 (9) {
        public $usageReference =>
        string(12) "120011112191"
        public $subscriptionReference =>
        string(10) "67F3AD6A32"
        public $optionCode =>
        string(6) "USG_MN"
        public $usageStart =>
        string(19) "2020-07-06 12:00:00"
        public $usageEnd =>
        string(19) "2020-07-07 12:00:00"
        public $units =>
        int(30)
        public $description =>
        string(0) ""
        public $renewalOrderReference =>
        string(0) ""
      }
    }
```

## Error handling

| Error message description                                                                                                      | Error code      | Error message                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **LICENCECODE is not a valid licence code for the merchant**                                                                   | INPUT\_ERROR    | Usage was not added as the license code provided is invalid.                                                                                     |
| **OPTIONCODE is invalid for the Merchant and Licence or is not a usage-based option code**                                     | INPUT\_ERROR    | Usage was not added as the option code provided is invalid.                                                                                      |
| **Provided usage entries overlap within themselves or with existing usage entries**                                            | INPUT\_ERROR    | Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination. |
| **Provided date formats are unsupported**                                                                                      | INPUT\_ERROR    | Usage start format unsupported. Please use YYYY-MM-DD HH:MM:SS.                                                                                  |
|                                                                                                                                |                 | Usage end format unsupported. Please use YYYY-MM-DD HH:MM:SS.                                                                                    |
| **One or more mandatory parameters are missing or do not have the required format**                                            | INPUT\_ERROR    | Usage was not added as one or more of the mandatory parameters are missing.                                                                      |
|                                                                                                                                |                 | Usage was not added as one or more of the parameters do not match the required format.                                                           |
|                                                                                                                                |                 | Units not allowed.                                                                                                                               |
| **Provided usages' start date is prior to the subscription start date or end date is after the subscription expiration date.** | INPUT\_ERROR    | Usage interval out of bounds.                                                                                                                    |
| **Unexpected error happens**                                                                                                   | INTERNAL\_ERROR | \<unexpected\_error>                                                                                                                             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-requests/usage-management/add-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.