Custom Pricing Units v2

The Custom Pricing Unit object.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/custom_pricing_units

POST/v2/billing/custom_pricing_units/:id

GET/v2/billing/custom_pricing_units/:id

GET/v2/billing/custom_pricing_units

The CustomPricingUnit object

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.

The CustomPricingUnit object

{
  "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
}

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
}

Custom Pricing Units v2

The CustomPricingUnit object

Attributes

idstring

objectstring, value is "v2.billing.custom_pricing_unit"

activeboolean

createdtimestamp

display_namestring

livemodeboolean

lookup_keynullable string

metadatanullable map

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