Licensed Items v2

A LicensedItem represents any item that you bill customers for based on the subscribed quantity.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/licensed_items

POST/v2/billing/licensed_items/:id

GET/v2/billing/licensed_items/:id

GET/v2/billing/licensed_items

The LicensedItem object

Attributes

idstring
The ID of the LicensedItem.

objectstring, value is "v2.billing.licensed_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.

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.

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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. Maximum length of 100 characters.

The LicensedItem object

{
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Monthly fee item",
  "id": "bli_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "monthly-fee-item",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.licensed_item",
  "unit_label": "per month",
  "livemode": true
}

Create a LicensedItem v2

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

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.

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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. Maximum length of 100 characters.

Returns

Response attributes

idstring
The ID of the LicensedItem.

objectstring, value is "v2.billing.licensed_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.

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.

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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. 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.

POST /v2/billing/licensed_items

Server-side language

curl -X POST https://api.stripe.com/v2/billing/licensed_items \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "display_name": "Monthly fee item",
    "lookup_key": "monthly-fee-item",
    "metadata": {
        "key": "value"
    },
    "unit_label": "per month"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Monthly fee item",
  "id": "bli_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "monthly-fee-item",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.licensed_item",
  "unit_label": "per month",
  "livemode": true
}

Update a LicensedItem v2

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

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the LicensedItem 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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. Maximum length of 100 characters.

Returns

Response attributes

idstring
The ID of the LicensedItem.

objectstring, value is "v2.billing.licensed_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.

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.

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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. 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.

404licensed_item_not_found

Returned when the provided licensed_item ID cannot be found.

POST /v2/billing/licensed_items/:id

cURL

curl -X POST https://api.stripe.com/v2/billing/licensed_items/bli_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "display_name": "Updated Monthly fee item",
    "lookup_key": "updated-monthly-fee-item",
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new_value"
    },
    "unit_label": "every month"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Updated Monthly fee item",
  "id": "bli_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "updated-monthly-fee-item",
  "metadata": {
    "existing_key": "updated_value",
    "new_key": "new_value"
  },
  "object": "v2.billing.licensed_item",
  "unit_label": "every month",
  "livemode": true
}

Retrieve a LicensedItem v2

Retrieve a LicensedItem object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the LicensedItem to retrieve.

Returns

Response attributes

idstring
The ID of the LicensedItem.

objectstring, value is "v2.billing.licensed_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.

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.

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 “seat” for Checkout to display “(price) per seat”, or “environment” to display “(price) per environment”. Maximum length of 100 characters.

Error Codes

404licensed_item_not_found

Returned when the provided licensed_item ID cannot be found.

GET /v2/billing/licensed_items/:id

Server-side language

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

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Monthly fee item",
  "id": "bli_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "monthly-fee-item",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.licensed_item",
  "unit_label": "per month",
  "livemode": true
}

Licensed Items v2

The LicensedItem object

Attributes

idstring

objectstring, value is "v2.billing.licensed_item"

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_detailsnullable objectPreview feature

unit_labelnullable string

Create a LicensedItem v2

Parameters

display_namestringRequired

lookup_keystring

metadatamap

tax_detailsobjectPreview feature

unit_labelstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.licensed_item"

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_detailsnullable objectPreview feature

unit_labelnullable string

Update a LicensedItem v2

Parameters

idstringRequired

display_namestring

lookup_keystring

metadatamap

tax_detailsobjectPreview feature

unit_labelstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.licensed_item"

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_detailsnullable objectPreview feature

unit_labelnullable string

Retrieve a LicensedItem v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.licensed_item"

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_detailsnullable objectPreview feature

unit_labelnullable string