> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit a usage entry

> Use this API to set either a prorated gauge or increment a final value counter for a customer.

The `v2/usage` REST API is designed to handle both setting a **prorated** gauge and incrementing a **final value** counter for a specific customer in Salesbricks.

<Info>
  To utilize this endpoint, ensure that you are using the `v2/usage` API endpoint:

  `https://api.salesbricks.com/api/v2/usage`
</Info>

## Request: POST /v2/usage

### Parameters

| Field             | Type     | Required | Description                                                              |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------ |
| `transaction_id`  | String   | Yes      | The unique identifier for this usage entry transaction.                  |
| `subscription_id` | UUID     | Yes      | The **ID** of the Salesbricks subscription associated with the customer. |
| `brick_id`        | UUID     | Yes      | The **ID** of the associated Usage Brick.                                |
| `value`           | Integer  | Yes      | Required. This is the value to set for the Counter or Gauge (e.g., `1`). |
| `time`            | DateTime | Yes      | The timestamp indicating when the operation occurs in ISO 8601 format.   |
| `properties`      | Dict     | No       | Additional properties as a JSON dictionary object (optional).            |

## Response

* `201 Created` - if the usage entry is successfully submitted.
* `400 Bad Request` - if validation fails or required fields are missing.

```json theme={null}
{
  "message": "Usage entry submitted successfully."
}
```

## Example: Setting a Prorated Gauge

```bash theme={null}
POST /v2/usage
Content-Type: application/json
Authorization: Bearer <token>

{
  "transaction_id": "12345",
  "subscription_id": "00000000-0000-0000-0000-000000000000",
  "brick_id": "00000000-0000-0000-0000-000000000000",
  "value": 121,
  "time": "2024-09-16T10:15:30Z"
}
```

## Example: Incrementing a Final Value Counter

```bash theme={null}
POST /v2/usage
Content-Type: application/json
Authorization: Bearer <token>

{
  "transaction_id": "54321",
  "subscription_id": "00000000-0000-0000-0000-000000000000",
  "brick_id": "00000000-0000-0000-0000-000000000000",
  "value": 1,
  "time": "2024-09-16T10:15:30Z",
  "properties": {
    "source_worker": "8168cf7f-65e0-4f9a-aeb4-3e013ff71f89",
    "region": "us-east-1"
  }
}
```

## DELETE /v2/usage - Deleting a Usage Entry

To delete a usage entry, provide the `transaction_id` in the request body.

### Parameters

| Field            | Type   | Required | Description                                |
| ---------------- | ------ | -------- | ------------------------------------------ |
| `transaction_id` | String | Yes      | The unique identifier for the usage entry. |

### Response

* `200 OK` - if the usage entry is successfully deleted.
* `404 Not Found` - if the usage entry does not exist.

```json theme={null}
{
  "message": "Usage entry deleted successfully."
}
```

## PATCH /v2/usage - Updating a Usage Entry

To update a usage entry, provide the `transaction_id` and the fields to be updated.

### Parameters

| Field            | Type    | Required | Description                                       |
| ---------------- | ------- | -------- | ------------------------------------------------- |
| `transaction_id` | String  | Yes      | The unique identifier for the usage entry.        |
| `value`          | Integer | Yes      | Update the usage value.                           |
| `properties`     | Dict    | Optional | Update the properties dictionary (if applicable). |

### Response

* `200 OK` - if the usage entry is successfully updated.
* `400 Bad Request` - if validation fails or required fields are missing.
* `404 Not Found` - if the usage entry does not exist.

```json theme={null}
{
  "message": "Usage entry updated successfully."
}
```


## Related topics

- [Submit a usage entry](/api-reference/usage/post.md)
- [Create a usage entry](/api-reference/usage/create-a-usage-entry.md)
- [Update a usage entry](/api-reference/usage/patch.md)