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
}

List LicensedItems v2

List all LicensedItem 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 LicensedItem 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/licensed_items

Server-side language

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

Response

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

Service Actions v2

A ServiceAction represents a recurring, automated action that can be applied as part of a subscription.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/service_actions

GET/v2/billing/service_actions/:id

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

List LicensedItems v2

Parameters

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Service Actions v2