API Reference

Rate Cards

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Rate Card

post/rate-cards

Create Rate Card

Body ParametersExpand Collapse

billing_interval: "monthly" or "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: optional string

The description of the rate card displayed to the customer.

fixed_rates: optional array of object { name, price, description }

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 } or 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 = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

price_type: optional "flat"

Accepts one of the following:

"flat"

PackagePriceInput = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

package_units: number

rounding_behavior: "round_up" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "package"

Accepts one of the following:

"package"

description: optional string

The description of the rate displayed to the customer.

metadata: optional map[string]

usage_based_rates: optional array of object { name, price, pricing_metric_id, 3 more } or object { 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:

Simple = object { name, price, pricing_metric_id, 3 more }

name: string

The name of the rate displayed to the customer.

price: FlatPriceInput { amount, price_type } or 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 = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

price_type: optional "flat"

Accepts one of the following:

"flat"

PackagePriceInput = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

package_units: number

rounding_behavior: "round_up" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "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: optional string

The description of the rate displayed to the customer.

included_units: optional number

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

minimum0

Dimensional = object { dimensions, name, pricing_matrix, 4 more }

dimensions: array of object { key, values, description }

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 of string

A list of possible values for the dimension.

description: optional string

The description of the dimension.

name: string

The name of the rate displayed to the customer.

pricing_matrix: object { cells }

The pricing matrix of the rate.

cells: array of object { dimension_coordinates, price }

dimension_coordinates: map[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 } or PackagePriceInput { amount, package_units, rounding_behavior, price_type }

The price for the cell.

Accepts one of the following:

FlatPriceInput = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

price_type: optional "flat"

Accepts one of the following:

"flat"

PackagePriceInput = object { 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 or string

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

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

package_units: number

rounding_behavior: "round_up" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "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: optional string

The description of the rate displayed to the customer.

included_units: optional number

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

minimum0

ReturnsExpand Collapse

RateCardResource = object { id, billing_interval, created_at, 6 more }

id: string

The ID of the rate card.

billing_interval: "monthly" or "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 of object { id, description, name, price }

The fixed rates of the rate card.

id: string

description: string

name: string

price: FlatPriceOutput { amount, price_type } or 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 = object { 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: optional "flat"

Accepts one of the following:

"flat"

PackagePriceOutput = object { 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" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "package"

Accepts one of the following:

"package"

metadata: map[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 of object { id, description, included_units, 4 more } or object { id, description, dimensions, 5 more }

The usage based rates of the rate card.

Accepts one of the following:

Simple = object { id, description, included_units, 4 more }

id: string

description: string

included_units: number

name: string

price: FlatPriceOutput { amount, price_type } or 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 = object { 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: optional "flat"

Accepts one of the following:

"flat"

PackagePriceOutput = object { 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" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "package"

Accepts one of the following:

"package"

pricing_metric_id: string

usage_based_rate_type: optional "simple"

Accepts one of the following:

"simple"

Dimensional = object { id, description, dimensions, 5 more }

id: string

description: string

dimensions: array of object { description, key, values }

description: string

key: string

values: array of string

included_units: number

name: string

pricing_matrix: object { cells }

cells: array of object { dimension_coordinates, price }

dimension_coordinates: map[string]

price: FlatPriceOutput { amount, price_type } or 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 = object { 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: optional "flat"

Accepts one of the following:

"flat"

PackagePriceOutput = object { 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" or "round_down"

Accepts one of the following:

"round_up"

"round_down"

price_type: optional "package"

Accepts one of the following:

"package"

pricing_metric_id: string

usage_based_rate_type: optional "dimensional"

Accepts one of the following:

"dimensional"

description: optional string

The description of the rate card.

Create Rate Card

HTTP

HTTP

TypeScript

Python

Go

Terraform

curl https://api.uselark.ai/rate-cards \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $LARK_API_KEY" \
    -d '{
          "billing_interval": "monthly",
          "name": "Pro Plan"
        }'

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