# Update usage

Use the **updateSubscriptionUsage** method via SOAP API 6.0 to update a specific usage entry.

## Request parameters

| Parameters                | Type   | Required                                    | Description                                                                                                                                                                                                                |
| ------------------------- | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **merchantCode**          | String | Required                                    | The system-generated merchant ID.                                                                                                                                                                                          |
| **hash**                  | String | Required                                    | The MD5 hmac key for the request.                                                                                                                                                                                          |
| **sessionID**             | String | Required                                    | The system-generated code of the session.                                                                                                                                                                                  |
| **UsageReference**        | String | Required                                    | The system-generated reference code for the usage of the subscription.                                                                                                                                                     |
| **SubscriptionReference** | String | Required                                    | The system-generated reference code for the subscription.                                                                                                                                                                  |
| **Units**                 | Number | Optional (Optional if Description provided) | Number of units used.                                                                                                                                                                                                      |
| **Description**           | String | Optional (Optional if Units provided)       | 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 = '4A1D733696';
$usageReference = 120010776516;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->Units = 123;
    $subscriptionUsageRequest->Description = 'Units 123';
    $response = $client->updateSubscriptionUsage($sessionID, $subscriptionReference, $usageReference, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;
```

## Response

The **updateSubscriptionUsage** method via SOAP APIv6 returns the **Usage** object if successful.

```php
class stdClass#3 (8) {
      public $UsageReference =>
      120011112631
      public $SubscriptionReference =>
      "67F3AD6A32"
      public $OptionCode =>
      "USG_MN"
      public $UsageStart =>
      "2020-07-06 12:00:00"
      public $UsageEnd =>
      "2020-07-07 12:00:00"
      public $Units =>
      69
      public $Description =>
      ""
      public $RenewalOrderReference =>
      0
    }
```

## Error Handling

If unsuccessful, the **updateSubscriptionUsage** method via SOAP APIv6 will return one of the errors below.

| Error message description                                 | Error code            | Error message                                                                                                         |
| --------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Provided parameters lack the required type or format.     | MALFORMED\_PARAMETER  | One or more parameters lack the required format: SubscriptionReference must be a string.                              |
|                                                           | MALFORMED\_PARAMETER  | One or more parameters lack the required format: UsageReference must be a positive integer higher than or equal to 1. |
|                                                           | PARAMETER\_MISSING    | Please provide at least one of the following parameters: Units, Description.                                          |
|                                                           | MALFORMED\_PARAMETER  | One or more parameters lack the required format: Units must be a positive integer higher than or equal to 1.          |
|                                                           | MALFORMED\_PARAMETER  | One or more parameters lack the required format: Description must be a string.                                        |
| Subscription or usage line are not found.                 | NOT\_FOUND            | Subscription not found.                                                                                               |
|                                                           | NOT\_FOUND            | Usage line described does not exist.                                                                                  |
| Usage line is already billed.                             | ALREADY\_BILLED       | Usage was not updated as this usage was already billed.                                                               |
| The renewal process is in progress for this subscription. | RENEWAL\_IN\_PROGRESS | There is a renewal in progress for the provided usage line.                                                           |
| The usage was not changed after the update.               | NOTHING\_HAPPENED     | The usage has not been updated, nothing to change. The provided values are identical to the existing ones.            |
| An unexpected error happens.                              | GENERIC               | There has been an error updating the usage line. Please try again later.                                              |


---

# 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/update-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.