Create a custom pricing unit v2

Create a Custom Pricing Unit object.

Learn more about calling API v2 endpoints.

Parameters

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

lookup_keystring
An internal key you can use to search for a particular custom pricing unit item. Must be unique among 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.

Returns

Response attributes

idstring
Unique identifier for the object.

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

activeboolean
Whether the custom pricing unit is active.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 10 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 Custom Pricing Unit. 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.

Error Codes

400lookup_key_already_used

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

POST /v2/billing/custom_pricing_units

Server-side language

curl -X POST https://api.stripe.com/v2/billing/custom_pricing_units \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "display_name": "Unit #1",
    "lookup_key": "my-custom-pricing-unit-1",
    "metadata": {
        "key": "value"
    }
  }'

Response

{
  "active": true,
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Unit #1",
  "id": "cpu_61T4sQA90ELFdWUhl16Ss95I3tSQSib3S1PC0IDCSFCS",
  "lookup_key": "my-custom-pricing-unit-1",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.custom_pricing_unit",
  "livemode": true
}

Update a Custom Pricing Unit v2

Update a Custom Pricing Unit object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Custom Pricing Unit to update.

activeboolean
Whether the Custom Pricing Unit is active.

display_namestring
Description that customers will see in the invoice line item.

lookup_keystring
An internal key you can use to search for a particular CustomPricingUnit item.

metadatamap
Set of key-value pairs that you can attach to an object.

Returns

Response attributes

idstring
Unique identifier for the object.

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

activeboolean
Whether the custom pricing unit is active.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 10 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 Custom Pricing Unit. 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.

Error Codes

404custom_pricing_unit_not_found

Returned by CustomPricingUnit API when the custom pricing unit is not found.

POST /v2/billing/custom_pricing_units/:id

Server-side language

curl -X POST https://api.stripe.com/v2/billing/custom_pricing_units/cpu_61T4sQA90ELFdWUhl16Ss95I3tSQSib3S1PC0IDCSFCS \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "display_name": "Unit #1",
    "lookup_key": "my-custom-pricing-unit-1"
  }'

Response

{
  "active": true,
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Unit #1",
  "id": "cpu_61T4sQA90ELFdWUhl16Ss95I3tSQSib3S1PC0IDCSFCS",
  "lookup_key": "my-custom-pricing-unit-1",
  "metadata": {},
  "object": "v2.billing.custom_pricing_unit",
  "livemode": true
}

Retrieve a custom pricing unit v2

Retrieve a Custom Pricing Unit object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Custom Pricing Unit to retrieve.

Returns

Response attributes

idstring
Unique identifier for the object.

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

activeboolean
Whether the custom pricing unit is active.

createdtimestamp
Timestamp of when the object was created.

display_namestring
Description that customers will see in the invoice line item. Maximum length of 10 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 Custom Pricing Unit. 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.

Error Codes

404custom_pricing_unit_not_found

Returned by CustomPricingUnit API when the custom pricing unit is not found.

GET /v2/billing/custom_pricing_units/:id

Server-side language

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

Response

{
  "active": true,
  "created": "2025-01-01T00:00:00.000Z",
  "display_name": "Unit #1",
  "id": "cpu_61T4sQA90ELFdWUhl16Ss95I3tSQSib3S1PC0IDCSFCS",
  "lookup_key": "my-custom-pricing-unit-1",
  "metadata": {},
  "object": "v2.billing.custom_pricing_unit",
  "livemode": true
}

List Custom Pricing Units v2

List all Custom Pricing Unit objects.

Learn more about calling API v2 endpoints.

Parameters

activeboolean
Filter for active/inactive custom pricing units. Mutually exclusive with lookup_keys.

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

lookup_keysarray of strings
Filter by lookup keys. Mutually exclusive with active. You can specify up to 10 lookup keys.

pagestring
A cursor for use in pagination.

Returns

Response attributes

dataarray of objects
List of Custom Pricing Units.

next_page_urlnullable string
The URL to get the next page of results, if there are any.

previous_page_urlnullable string
The URL to get the previous page of results, if there are any.

GET /v2/billing/custom_pricing_units

Server-side language

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

Response

{
  "data": [
    {
      "active": true,
      "created": "2025-01-01T00:00:00.000Z",
      "display_name": "Unit #1",
      "id": "cpu_61T4sQA90ELFdWUhl16Ss95I3tSQSib3S1PC0IDCSFCS",
      "lookup_key": "my-custom-pricing-unit-1",
      "metadata": {},
      "object": "v2.billing.custom_pricing_unit",
      "livemode": true
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Licensed Items v2

A Licensed Item 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

Create a custom pricing unit v2

Parameters

display_namestringRequired

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.custom_pricing_unit"

activeboolean

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

Update a Custom Pricing Unit v2

Parameters

idstringRequired

activeboolean

display_namestring

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.custom_pricing_unit"

activeboolean

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

Retrieve a custom pricing unit v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.custom_pricing_unit"

activeboolean

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

List Custom Pricing Units v2

Parameters

activeboolean

limitinteger

lookup_keysarray of strings

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Licensed Items v2