Clerk API (unofficial showcase)
POST/billing/prices

Create a custom billing price

Creates a custom price for a billing plan. Custom prices allow you to offer different pricing to specific customers while maintaining the same plan structure.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields

Parameters for creating a custom price

plan_idstringrequired
The ID of the plan this price belongs to.
currencystringoptional
The currency code (e.g., "USD"). Defaults to USD.
Default:USD
amountintegerrequired
The monthly amount in cents. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents).
annual_monthly_amountintegeroptional
The monthly amount in cents when billed annually. Use `0` for a complimentary price. Positive amounts must be at least $1 (100 cents).
descriptionstringoptional
An optional description for this custom price.
supported_billing_periodsstringoptional
Which billing periods this price supports. Inferred from amounts if omitted.
Allowed:monthannualboth

6 status codes
200A billing price.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:commerce_price
idstringrequired
Unique identifier for the price.
plan_idstringrequired
Unique identifier for the associated plan.
instance_idstringrequired
Unique identifier for the instance.
currencystringrequired
The currency code (e.g., "USD").
currency_symbolstringrequired
The currency symbol (e.g., "$").
amountintegerrequired
The amount in cents for the price.
annual_monthly_amountintegerrequired
The monthly amount in cents when billed annually.
feeobjectrequired
annual_monthly_feeobjectrequired
descriptionstringoptional
The description of the price.
is_defaultbooleanrequired
Whether this price is the default price for its plan.
created_atintegerrequired
Unix timestamp (milliseconds) of creation.
supported_billing_periodsstringrequired
Which billing periods this price supports.
Allowed:monthannualboth
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
500Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters. A 500 is returned: Request was not successful.