# Create a usage > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). [Idempotency Supported](/docs/api/idempotency) **Advanced Usage-Based Billing** For high-scale usage ingestion, use [Advanced Usage-Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages) with the [Usage Events API](/docs/api/usage_events). The Usage Events API supports schemaless event ingestion at scale, including [individual events](/docs/api/usage_events/create-a-usage-event), [batch ingestion](/docs/api/usage_events/ingest-usages-in-batch), and [usage file ingestion](/docs/api/usage_files/usage-file-object). Creates a usage record for an item price in a subscription. The item price must belong to a [`metered`](/docs/api/items/item-object#metered) item. This endpoint is part of the [Usages API](/docs/api/usages) for **Automated Metered Billing**. **Max Usages** Legacy metered billing applies per-subscription usage limits over the subscription lifetime. [Contact Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) for the limit applicable to your site or to request an increase. For high-volume usage at scale, see [Usage-Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages). ## Sample Request #### cURL ```bash curl https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKXhP/usages \ -u {site_api_key}:\ -d item_price_id="silver-usd" \ -d usage_date=1601718989 \ -d note="Day 1 usage from __test__XpbBrciSCKqKUcN" \ -d quantity="5" ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = Usage.Create("__test__XpbBrciSCKqKXhP") .ItemPriceId("silver-usd") .UsageDate(1601718989) .Note("Day 1 usage from __test__XpbBrciSCKqKUcN") .Quantity("5") .Request(); Usage usage = result.Usage; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" usageAction "github.com/chargebee/chargebee-go/v3/actions/usage" "github.com/chargebee/chargebee-go/v3/models/usage" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := usageAction.Create("__test__XpbBrciSCKqKXhP", &usage.CreateRequestParams{ ItemPriceId : "silver-usd", UsageDate : chargebee.Int64(1601718989), Note : "Day 1 usage from __test__XpbBrciSCKqKUcN", Quantity : "5", }).Request() if err != nil { fmt.Println(err) } else { Usage := res.Usage } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.UsageCreateRequest{ ItemPriceId : "silver-usd", UsageDate : chargebee.Int64(1601718989), Note : "Day 1 usage from __test__XpbBrciSCKqKUcN", Quantity : "5", } res, err := client.Usage.Create("__test__XpbBrciSCKqKXhP", req) if err != nil { fmt.Println(err) } else { Usage := res.Usage } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; import java.sql.Timestamp; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = Usage.create("__test__XpbBrciSCKqKXhP") .itemPriceId("silver-usd") .usageDate(new Timestamp(1601718989L * 1000)) .note("Day 1 usage from __test__XpbBrciSCKqKUcN") .quantity("5") .request(); Usage usage = result.usage(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.usage.Usage; import com.chargebee.v4.models.usage.params.UsageCreateParams; import com.chargebee.v4.models.usage.responses.UsageCreateResponse; import java.sql.Timestamp; public class UsageCreate { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); UsageCreateParams params = UsageCreateParams.builder() .itemPriceId("silver-usd") .usageDate(new Timestamp(1601718989L * 1000)) .note("Day 1 usage from __test__XpbBrciSCKqKUcN") .quantity("5") .build(); UsageCreateResponse response = client .usages() .create("__test__XpbBrciSCKqKXhP", params); Usage usage = response.getUsage(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.usage.create("__test__XpbBrciSCKqKXhP", { item_price_id: "silver-usd", usage_date: 1601718989, note: "Day 1 usage from __test__XpbBrciSCKqKUcN", quantity: "5" }); console.log(result); const usage = result.usage; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->usage()->create("__test__XpbBrciSCKqKXhP", [ "item_price_id" => "silver-usd", "usage_date" => 1601718989, "note" => "Day 1 usage from __test__XpbBrciSCKqKUcN", "quantity" => "5" ]); $usage = $result->usage; ``` #### Python ```python from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.Usage.create("__test__XpbBrciSCKqKXhP", cb_client.Usage.CreateParams( item_price_id="silver-usd", usage_date=1601718989, note="Day 1 usage from __test__XpbBrciSCKqKUcN", quantity="5" ) ) usage = response.usage ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::Usage.create("__test__XpbBrciSCKqKXhP",{ :item_price_id => "silver-usd", :usage_date => 1601718989, :note => "Day 1 usage from __test__XpbBrciSCKqKUcN", :quantity => "5" }) usage = result.usage ``` ## Sample Response ```json { "usage": { "created_at": 1601708189, "id": "usage_XpbBrciSCKqKcLS", "item_price_id": "silver-usd", "note": "Day 1 usage from __test__XpbBrciSCKqKUcN", "object": "usage", "quantity": "5", "resource_version": 1601708189381, "subscription_id": "__test__XpbBrciSCKqKXhP", "updated_at": 1601708189, "usage_date": 1601718989 } } ``` ## URL Format **POST** https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/usages ## Input Parameters - `id` (optional, string, max chars=100) A unique and immutable id for the usage. If not provided, it is autogenerated. - `item_price_id` (required, string, max chars=100) The id of the [item price](/docs/api/item_prices) to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically. - `quantity` (required, string, max chars=40) The quantity specified for this usage record. - `usage_date` (required, timestamp(UTC) in seconds) The time at which this usage occurred. Chargebee bills only those usages whose `usage_date` falls within a time when the subscription `status` was `active` or `non_renewing`. However, the remaining usage records are still stored and are [retrievable](/docs/api/usages/retrieve-a-usage). **Note:** If `usage_date` corresponds to a time already invoiced, then it is stored but never invoiced unless the [invoice is regenerated](/docs/api/subscriptions/regenerate-an-invoice) . - `note` (optional, string, max chars=500) A note for this usage record. This note is not displayed on any customer-facing document or interface such as [invoice PDFs](/docs/api/invoices/retrieve-invoice-as-pdf) or [Hosted Pages](/docs/api/hosted_pages) . ## Returns - `usage` (Usage object) Resource object representing usage