API Reference

Rate Cards

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Rate Card

client.rateCards.create(RateCardCreateParams { billing_interval, name, description, 3 more } body, RequestOptionsoptions?): RateCardResource { id, billing_interval, created_at, 6 more }

post/rate-cards

Create Rate Card

ParametersExpand Collapse

body: RateCardCreateParams { billing_interval, name, description, 3 more }

billing_interval: "monthly" | "yearly"

How often the customer will be billed for this rate card.

Accepts one of the following:

"monthly"

"yearly"

name: string

The name of the rate card displayed to the customer.

description?: string | null

The description of the rate card displayed to the customer.

fixed_rates?: Array<FixedRate>

The fixed rates of the rate card. These are billed at the start of each billing cycle.

name: string

The name of the rate displayed to the customer.

price: FlatPriceInput { amount, price_type } | PackagePriceInput { amount, package_units, rounding_behavior, price_type }

Flat price is a price that linearly scales with the quantity.

Accepts one of the following:

FlatPriceInput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceInput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

description?: string | null

The description of the rate displayed to the customer.

metadata?: Record<string, string>

usage_based_rates?: Array<CreateSimpleUsageBasedRateRequest { name, price, pricing_metric_id, 3 more } | CreateDimensionalUsageBasedRateRequest { dimensions, name, pricing_matrix, 4 more } >

The usage based rates of the rate card. These are billed at the end of each billing cycle.

Accepts one of the following:

CreateSimpleUsageBasedRateRequest { name, price, pricing_metric_id, 3 more }

name: string

The name of the rate displayed to the customer.

price: FlatPriceInput { amount, price_type } | PackagePriceInput { amount, package_units, rounding_behavior, price_type }

Flat price is a price that linearly scales with the quantity.

Accepts one of the following:

FlatPriceInput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceInput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

pricing_metric_id: string

The ID of the pricing metric to use for this rate.

usage_based_rate_type: "simple"

Accepts one of the following:

"simple"

description?: string | null

The description of the rate displayed to the customer.

included_units?: number

The number of units included in the rate before the price is applied.

minimum0

CreateDimensionalUsageBasedRateRequest { dimensions, name, pricing_matrix, 4 more }

dimensions: Array<Dimension>

The dimensions of the rate.

key: string

The name of the dimension. This is used to identify the dimension in the pricing matrix.

values: Array<string>

A list of possible values for the dimension.

description?: string | null

The description of the dimension.

name: string

The name of the rate displayed to the customer.

pricing_matrix: PricingMatrix { cells }

The pricing matrix of the rate.

cells: Array<Cell>

dimension_coordinates: Record<string, string>

A key-value mapping of dimension keys and values to identify the price for a given set of dimension values.

price: FlatPriceInput { amount, price_type } | PackagePriceInput { amount, package_units, rounding_behavior, price_type }

The price for the cell.

Accepts one of the following:

FlatPriceInput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceInput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountInput { currency_code, value }

currency_code: string

The currency code of the amount.

value: number | string

The value of the amount in the smallest unit of the currency.

Accepts one of the following:

number

string

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

pricing_metric_id: string

The ID of the pricing metric to use for this rate.

usage_based_rate_type: "dimensional"

Accepts one of the following:

"dimensional"

description?: string | null

The description of the rate displayed to the customer.

included_units?: number

The number of units included in the rate before the price is applied.

minimum0

ReturnsExpand Collapse

RateCardResource { id, billing_interval, created_at, 6 more }

id: string

The ID of the rate card.

billing_interval: "monthly" | "yearly"

How often the customer will be billed for this rate card.

Accepts one of the following:

"monthly"

"yearly"

created_at: string

The date and time the rate card was created.

formatdate-time

fixed_rates: Array<FixedRate>

The fixed rates of the rate card.

id: string

description: string | null

name: string

price: FlatPriceOutput { amount, price_type } | PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Flat price is a price that linearly scales with the quantity.

Accepts one of the following:

FlatPriceOutput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

metadata: Record<string, string>

Additional metadata about the rate card. You may use this to store any custom data about the rate card.

name: string

The name of the rate card.

updated_at: string

The date and time the rate card was last updated.

formatdate-time

usage_based_rates: Array<SimpleUsageBasedRateInterface { id, description, included_units, 4 more } | DimensionalUsageBasedRateInterface { id, description, dimensions, 5 more } >

The usage based rates of the rate card.

Accepts one of the following:

SimpleUsageBasedRateInterface { id, description, included_units, 4 more }

id: string

description: string | null

included_units: number

name: string

price: FlatPriceOutput { amount, price_type } | PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Flat price is a price that linearly scales with the quantity.

Accepts one of the following:

FlatPriceOutput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

pricing_metric_id: string

usage_based_rate_type?: "simple"

Accepts one of the following:

"simple"

DimensionalUsageBasedRateInterface { id, description, dimensions, 5 more }

id: string

description: string | null

dimensions: Array<Dimension>

description: string | null

key: string

values: Array<string>

included_units: number

name: string

pricing_matrix: PricingMatrix { cells }

cells: Array<Cell>

dimension_coordinates: Record<string, string>

price: FlatPriceOutput { amount, price_type } | PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Flat price is a price that linearly scales with the quantity.

Accepts one of the following:

FlatPriceOutput { amount, price_type }

Flat price is a price that linearly scales with the quantity.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

price_type?: "flat"

Accepts one of the following:

"flat"

PackagePriceOutput { amount, package_units, rounding_behavior, price_type }

Package price is a price that is charged for a fixed number of units. For example, $10 per 1000 units. If the quantity is not a multiple of the package units, the rounding behavior will be applied.

amount: AmountOutput { currency_code, value }

currency_code: string

The currency code of the amount.

value: string

The value of the amount in the smallest unit of the currency.

package_units: number

rounding_behavior: "round_up" | "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type?: "package"

Accepts one of the following:

"package"

pricing_metric_id: string

usage_based_rate_type?: "dimensional"

Accepts one of the following:

"dimensional"

description?: string | null

The description of the rate card.

Create Rate Card

TypeScript

HTTP

TypeScript

Python

Go

Terraform

import Lark from 'lark-billing';

const client = new Lark({
  apiKey: 'My API Key',
});

const rateCardResource = await client.rateCards.create({
  billing_interval: 'monthly',
  name: 'Pro Plan',
  description: 'For production applicatidddons with moderate usage.',
  fixed_rates: [
    { name: 'Base Rate', price: { price_type: 'flat', amount: { value: 2500, currency_code: 'usd' } } },
  ],
  metadata: {},
  usage_based_rates: [
    {
      usage_based_rate_type: 'simple',
      name: 'Compute Hours',
      price: { price_type: 'flat', amount: { value: 100, currency_code: 'usd' } },
      included_units: 30,
      pricing_metric_id: 'pmtr_GlX5Tcm2HOn00CoRTFxw2Amw',
    },
  ],
});

console.log(rateCardResource.id);

200 example

{
  "id": "rc_jQK2n0wutCj6bBcAIrL6o07g",
  "billing_interval": "monthly",
  "created_at": "2025-11-01T00:00:00Z",
  "fixed_rates": [
    {
      "id": "fr_04EjnYJoQLC7gtLKI6mPzZny",
      "description": "description",
      "name": "Base Rate",
      "price": {
        "amount": {
          "currency_code": "usd",
          "value": "2500"
        },
        "price_type": "flat"
      }
    }
  ],
  "metadata": {},
  "name": "Pro Plan",
  "updated_at": "2025-11-01T00:00:00Z",
  "usage_based_rates": [
    {
      "id": "ubr_zoXOJrDXlGGJWRNq3HqFYhbP",
      "description": "description",
      "included_units": 30,
      "name": "Compute Hours",
      "price": {
        "amount": {
          "currency_code": "usd",
          "value": "100"
        },
        "price_type": "flat"
      },
      "pricing_metric_id": "pmtr_GlX5Tcm2HOn00CoRTFxw2Amw",
      "usage_based_rate_type": "simple"
    }
  ],
  "description": "For production applications with moderate usage."
}

Returns Examples

200 example

{
  "id": "rc_jQK2n0wutCj6bBcAIrL6o07g",
  "billing_interval": "monthly",
  "created_at": "2025-11-01T00:00:00Z",
  "fixed_rates": [
    {
      "id": "fr_04EjnYJoQLC7gtLKI6mPzZny",
      "description": "description",
      "name": "Base Rate",
      "price": {
        "amount": {
          "currency_code": "usd",
          "value": "2500"
        },
        "price_type": "flat"
      }
    }
  ],
  "metadata": {},
  "name": "Pro Plan",
  "updated_at": "2025-11-01T00:00:00Z",
  "usage_based_rates": [
    {
      "id": "ubr_zoXOJrDXlGGJWRNq3HqFYhbP",
      "description": "description",
      "included_units": 30,
      "name": "Compute Hours",
      "price": {
        "amount": {
          "currency_code": "usd",
          "value": "100"
        },
        "price_type": "flat"
      },
      "pricing_metric_id": "pmtr_GlX5Tcm2HOn00CoRTFxw2Amw",
      "usage_based_rate_type": "simple"
    }
  ],
  "description": "For production applications with moderate usage."
}