---
title: "Create usage charge"
method: POST
path: "/subscriptions/{subscriptionId}/usages/{usageId}/charges"
tags: ["Subscriptions"]
---

# Create usage charge

`POST /subscriptions/{subscriptionId}/usages/{usageId}/charges`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/subscriptions/{subscriptionId}/usages/{usageId}/charges`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Creates a one-off charge (quantity 1) against a usage product the account is subscribed to.
The charge is processed asynchronously.
            
Important considerations:
* The usage product must already be subscribed on the account's usage subscription
* The price must exist on the usage product and be active
* Charges are rejected while the usage subscription is overdue (past due, unpaid, canceled, or incomplete-expired)
* The caller must be authorized for usage billing on the product

## Path parameters

- `subscriptionId` string, required
- `usageId` string, uuid, required

## Request body

- CreateUsageChargeRequest
  - `priceId` string, uuid, nullable: The price to charge for this usage product.
  - `matterId` string, uuid, nullable: The matter id associated with the usage charge.
  - `description` string, nullable: The description associated with the usage charge.
  - `metadata` object, nullable: Optional metadata associated with the usage charge.

## Response `202`

When request is accepted. Returns a 'Link' object to the created charge.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When the request is missing or invalid, the usage is not subscribed, the price is inactive, or the account is overdue.
- `403`: When the user is not authorized for usage billing on the product.
- `404`: When the usage subscription, usage product, or price does not exist.
- `500`: When the service cannot resolve a billable price from the usage subscription configuration.

## Changes

- **2026-10-28** `2fe552c5d11d`: 1 info
  - added the non-success response with the status `500`
- **2026-07-26** `197984da9b42`: 6 info
  - the request property `allOf[#/components/schemas/CreateUsageChargeRequest]/priceId` became nullable (media type: application/json-patch+json)
  - the request property `allOf[#/components/schemas/CreateUsageChargeRequest]/priceId` became nullable (media type: application/json)
  - the request property `allOf[#/components/schemas/CreateUsageChargeRequest]/priceId` became nullable (media type: application/*+json)
  - the request property `allOf[#/components/schemas/CreateUsageChargeRequest]/priceId` became optional (media type: application/json-patch+json)
  - …2 more

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/:subscriptionId/usages/:usageId/charges/post.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)