Create a metered item v2

Create a MeteredItem 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 MeteredItem.

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
The ID of the MeteredItem.

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 MeteredItem.

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-07-30.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 MeteredItem object. At least one of the fields is required.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the MeteredItem 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
The ID of the MeteredItem.

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 MeteredItem.

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-07-30.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 MeteredItem object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the MeteredItem to retrieve.

Returns

Response attributes

idstring
The ID of the MeteredItem.

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 MeteredItem.

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-07-30.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
}

List metered items v2

List all MeteredItem objects in reverse chronological order of creation.

Learn more about calling API v2 endpoints.

Parameters

limitinteger
Optionally set the maximum number of results per page. Defaults to 20.

pagestring
Opaque page token.

Returns

Response attributes

dataarray of objects
The retrieved MeteredItem objects.

next_page_urlnullable string
The URL of the next page of results, if there is one.

previous_page_urlnullable string
The URL of the previous page of results, if there is one.

GET /v2/billing/metered_items

Server-side language

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

Response

{
  "data": [
    {
      "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
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

MeteredItem event types v2

This is a list of all public thin events we currently send for updates to MeteredItem, which are continually evolving and expanding. The payload of thin events is unversioned. During processing, you must fetch the versioned event from the API or fetch the resource’s current state.

Event types

Type

Filter events by type

Type

v2.billing.metered_item.created

Occurs when a MeteredItem is created.

Attributes

idstring
Unique identifier for the event.

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

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

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

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.metered_item.created"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2BpA",
  "object": "v2.core.event",
  "type": "v2.billing.metered_item.created",
  "livemode": true,
  "reason": {
    "type": "request",
    "request": {
      "id": "req_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2FpE",
      "idempotency_key": "idem_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2GpH"
    }
  },
  "related_object": {
    "id": "bli_61SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2KpL",
    "type": "v2.billing.metered_item",
    "url": "/v2/billing/metered_items/bli_61SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2KpL"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2BpA",
  "object": "v2.core.event",
  "type": "v2.billing.metered_item.created",
  "livemode": true,
  "reason": {
    "type": "request",
    "request": {
      "id": "req_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2FpE",
      "idempotency_key": "idem_65SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2GpH"
    }
  },
  "related_object": {
    "id": "bli_61SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2KpL",
    "type": "v2.billing.metered_item",
    "url": "/v2/billing/metered_items/bli_61SJYFLbcODkA5Zd7rZ16RuKJoESSQUtPVJKIgeI4D2KpL"
  },
  "data": {}
}

v2.billing.metered_item.updated

Occurs when a MeteredItem is updated.

Attributes

idstring
Unique identifier for the event.

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

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

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

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.metered_item.updated"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJhYZDkX1uJ5gsI1Z16RuKJoESSQUtPVJKIgeI4D20zW",
  "object": "v2.core.event",
  "type": "v2.billing.metered_item.updated",
  "livemode": true,
  "reason": {
    "type": "request",
    "request": {
      "id": "req_65SJhXZEhB4oQ0Csu16RuKJoESSQUtPVJKIgeI4D26Fi",
      "idempotency_key": "idem_65SJhWUFiC5pR1Dtv16RuKJoESSQUtPVJKIgeI4D27Gj"
    }
  },
  "related_object": {
    "id": "bli_61SJhVUEbdTBR3Cns16RuKJoESSQUtPVJKIgeI4D25Mc",
    "type": "v2.billing.metered_item",
    "url": "/v2/billing/metered_items/bli_61SJhVUEbdTBR3Cns16RuKJoESSQUtPVJKIgeI4D25Mc"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJhYZDkX1uJ5gsI1Z16RuKJoESSQUtPVJKIgeI4D20zW",
  "object": "v2.core.event",
  "type": "v2.billing.metered_item.updated",
  "livemode": true,
  "reason": {
    "type": "request",
    "request": {
      "id": "req_65SJhXZEhB4oQ0Csu16RuKJoESSQUtPVJKIgeI4D26Fi",
      "idempotency_key": "idem_65SJhWUFiC5pR1Dtv16RuKJoESSQUtPVJKIgeI4D27Gj"
    }
  },
  "related_object": {
    "id": "bli_61SJhVUEbdTBR3Cns16RuKJoESSQUtPVJKIgeI4D25Mc",
    "type": "v2.billing.metered_item",
    "url": "/v2/billing/metered_items/bli_61SJhVUEbdTBR3Cns16RuKJoESSQUtPVJKIgeI4D25Mc"
  },
  "data": {}
}

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

List metered items v2

Parameters

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

MeteredItem event types v2

Event types

Attributes

idstring

objectstring, value is "v2.core.event"

contextnullable string

createdtimestamp

livemodeboolean