Billing

Create a custom billing price

Changed on

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.

post/billing/prices

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/billing/prices
  • Auth: HTTP bearer

Request body

plan_idstring required

The ID of the plan this price belongs to.

currencystring

The currency code (e.g., "USD"). Defaults to USD.

amountinteger nullable required

The monthly amount in cents. Use 0 for a complimentary price. Positive amounts must be at least $1 (100 cents).

annual_monthly_amountinteger nullable

The monthly amount in cents when billed annually. Use 0 for a complimentary price. Positive amounts must be at least $1 (100 cents).

descriptionstring

An optional description for this custom price.

supported_billing_periods'month' | 'annual' | 'both'

Which billing periods this price supports. Inferred from amounts if omitted.

Response

A billing price.

object'commerce_price' required

String representing the object's type. Objects of the same type share the same value.

idstring required

Unique identifier for the price.

plan_idstring required

Unique identifier for the associated plan.

instance_idstring required

Unique identifier for the instance.

currencystring required

The currency code (e.g., "USD").

currency_symbolstring required

The currency symbol (e.g., "$").

amountinteger required

The amount in cents for the price.

annual_monthly_amountinteger required

The monthly amount in cents when billed annually.

descriptionstring nullable

The description of the price.

is_defaultboolean required

Whether this price is the default price for its plan.

created_atinteger required

Unix timestamp (milliseconds) of creation.

supported_billing_periods'month' | 'annual' | 'both' required

Which billing periods this price supports.

Changes

  • 2025-11-104db0b9e2d5e6Revision changes
    • info

      added the new optional request property

    • info

      added the required property to the response with the status

  • 2025-11-10b1a5498e4465Revision changes
    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • breaking

      the response's property type changed from object to no type for status

    • breaking

      the response's property type changed from object to no type for status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status