Metered Items v2

A Metered Item represents any item that you bill customers for based on how much they use it, such as hourly cloud CPU usage or tokens generated by an AI service.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/metered_items

POST/v2/billing/metered_items/:id

GET/v2/billing/metered_items/:id

GET/v2/billing/metered_items

The MeteredItem object

Attributes

idstring
Unique identifier for the object.

objectstring, value is "v2.billing.metered_item"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 250 characters.

invoice_presentation_dimensionsarray of stringsPreview feature
Optional array of Meter dimensions to group event dimension keys for invoice line items.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billable item. Maximum length of 200 characters.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

meterstring
ID of the Meter that measures usage for this Metered Item.

meter_segment_conditionsarray of objectsPreview feature
Optional array of Meter segments to filter event dimension keys for billing.

tax_detailsnullable objectPreview feature
Stripe Tax details.

unit_labelnullable string
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters.

The MeteredItem object

{
  "id": "bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY",
  "object": "v2.billing.metered_item",
  "created": "2025-03-27T00:04:48.000Z",
  "display_name": "Premium Chat API",
  "lookup_key": null,
  "metadata": {},
  "meter": "mtr_test_61SD5KZ52hzuwbPJE41H5wvQ9UC0V34K",
  "meter_segment_conditions": [],
  "invoice_presentation_dimensions": [],
  "unit_label": null,
  "livemode": false
}

Create a metered item v2

Create a Metered Item object.

Learn more about calling API v2 endpoints.

Parameters

display_namestringRequired
Description that customers will see in the invoice line item. Maximum length of 250 characters.

meterstringRequired
ID of the Meter that measures usage for this Metered Item.

invoice_presentation_dimensionsarray of stringsPreview feature
Optional array of Meter dimensions to group event dimension keys for invoice line items.

lookup_keystring
An internal key you can use to search for a particular billable item. Must be unique among billable items. Maximum length of 200 characters.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

meter_segment_conditionsarray of objectsPreview feature
Optional array of Meter segments to filter event dimension keys for billing.

tax_detailsobjectPreview feature
Stripe Tax details.

unit_labelstring
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters.

Returns

Response attributes

idstring
Unique identifier for the object.

objectstring, value is "v2.billing.metered_item"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 250 characters.

invoice_presentation_dimensionsarray of stringsPreview feature
Optional array of Meter dimensions to group event dimension keys for invoice line items.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billable item. Maximum length of 200 characters.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

meterstring
ID of the Meter that measures usage for this Metered Item.

meter_segment_conditionsarray of objectsPreview feature
Optional array of Meter segments to filter event dimension keys for billing.

tax_detailsnullable objectPreview feature
Stripe Tax details.

unit_labelnullable string
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters.

Error Codes

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

400tax_code_invalid

Returned when tax_code.value does not correspond to a Stripe PTC.

404meter_not_found

Returned when the provided meter ID cannot be found.

POST /v2/billing/metered_items

Server-side language

curl -X POST https://api.stripe.com/v2/billing/metered_items \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "display_name": "Chat API",
    "meter": "mtr_61SD5KZ52hzuwbPJE41H5wvQ9UC0V34K"
  }'

Response

{
  "id": "bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY",
  "object": "v2.billing.metered_item",
  "created": "2025-03-27T00:04:48.000Z",
  "display_name": "Chat API",
  "lookup_key": null,
  "metadata": {},
  "meter": "mtr_test_61SD5KZ52hzuwbPJE41H5wvQ9UC0V34K",
  "unit_label": null,
  "livemode": true
}

Update a metered item v2

Update a Metered Item object. At least one of the fields is required.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the Metered Item to update.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 250 characters.

lookup_keystring
An internal key you can use to search for a particular billable item. Maximum length of 200 characters. To remove the lookup_key from the object, set it to null in the request.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

tax_detailsobjectPreview feature
Stripe Tax details.

unit_labelstring
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters. To remove the unit_label from the object, set it to null in the request.

Returns

Response attributes

idstring
Unique identifier for the object.

objectstring, value is "v2.billing.metered_item"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 250 characters.

invoice_presentation_dimensionsarray of stringsPreview feature
Optional array of Meter dimensions to group event dimension keys for invoice line items.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billable item. Maximum length of 200 characters.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

meterstring
ID of the Meter that measures usage for this Metered Item.

meter_segment_conditionsarray of objectsPreview feature
Optional array of Meter segments to filter event dimension keys for billing.

tax_detailsnullable objectPreview feature
Stripe Tax details.

unit_labelnullable string
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters.

Error Codes

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

400tax_code_invalid

Returned when tax_code.value does not correspond to a Stripe PTC.

404metered_item_not_found

Returned when the provided metered_item ID cannot be found.

POST /v2/billing/metered_items/:id

Server-side language

curl -X POST https://api.stripe.com/v2/billing/metered_items/bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "display_name": "Premium Chat API"
  }'

Response

{
  "id": "bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY",
  "object": "v2.billing.metered_item",
  "created": "2025-03-27T00:04:48.000Z",
  "display_name": "Premium Chat API",
  "lookup_key": null,
  "metadata": {},
  "meter": "mtr_test_61SD5KZ52hzuwbPJE41H5wvQ9UC0V34K",
  "unit_label": null,
  "livemode": true
}

Retrieve a metered item v2

Retrieve a Metered Item object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the Metered Item to retrieve.

Returns

Response attributes

idstring
Unique identifier for the object.

objectstring, value is "v2.billing.metered_item"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 250 characters.

invoice_presentation_dimensionsarray of stringsPreview feature
Optional array of Meter dimensions to group event dimension keys for invoice line items.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for a particular billable item. Maximum length of 200 characters.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

meterstring
ID of the Meter that measures usage for this Metered Item.

meter_segment_conditionsarray of objectsPreview feature
Optional array of Meter segments to filter event dimension keys for billing.

tax_detailsnullable objectPreview feature
Stripe Tax details.

unit_labelnullable string
The unit to use when displaying prices for this billable item in places like Checkout. For example, set this field to “CPU-hour” for Checkout to display “(price) per CPU-hour”, or “1 million events” to display “(price) per 1 million events”. Maximum length of 100 characters.

Error Codes

404metered_item_not_found

Returned when the provided metered_item ID cannot be found.

GET /v2/billing/metered_items/:id

Server-side language

curl https://api.stripe.com/v2/billing/metered_items/bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"

Response

{
  "id": "bli_test_61SGRtYMvrf176Kmm16RM8VQESSQ4t1K5KYFAmKUSVdY",
  "object": "v2.billing.metered_item",
  "created": "2025-03-27T00:04:48.000Z",
  "display_name": "Premium Chat API",
  "lookup_key": null,
  "metadata": {},
  "meter": "mtr_test_61SD5KZ52hzuwbPJE41H5wvQ9UC0V34K",
  "unit_label": null,
  "livemode": false
}

Metered Items v2

The MeteredItem object

Attributes

idstring

objectstring, value is "v2.billing.metered_item"

createdtimestamp

display_namestring

invoice_presentation_dimensionsarray of stringsPreview feature

livemodeboolean

lookup_keynullable string

metadatanullable map

meterstring

meter_segment_conditionsarray of objectsPreview feature

tax_detailsnullable objectPreview feature

unit_labelnullable string

Create a metered item v2

Parameters

display_namestringRequired

meterstringRequired

invoice_presentation_dimensionsarray of stringsPreview feature

lookup_keystring

metadatamap

meter_segment_conditionsarray of objectsPreview feature

tax_detailsobjectPreview feature

unit_labelstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.metered_item"

createdtimestamp

display_namestring

invoice_presentation_dimensionsarray of stringsPreview feature

livemodeboolean

lookup_keynullable string

metadatanullable map

meterstring

meter_segment_conditionsarray of objectsPreview feature

tax_detailsnullable objectPreview feature

unit_labelnullable string

Update a metered item v2

Parameters

idstringRequired

display_namestring

lookup_keystring

metadatamap

tax_detailsobjectPreview feature

unit_labelstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.metered_item"

createdtimestamp

display_namestring

invoice_presentation_dimensionsarray of stringsPreview feature

livemodeboolean

lookup_keynullable string

metadatanullable map

meterstring

meter_segment_conditionsarray of objectsPreview feature

tax_detailsnullable objectPreview feature

unit_labelnullable string

Retrieve a metered item v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.metered_item"

createdtimestamp

display_namestring

invoice_presentation_dimensionsarray of stringsPreview feature

livemodeboolean

lookup_keynullable string

metadatanullable map

meterstring

meter_segment_conditionsarray of objectsPreview feature

tax_detailsnullable objectPreview feature

unit_labelnullable string