Product Prices

Download schema

Prices for catalogue products. A price ID is what an invoice / quote / order-confirmation line references to bill a real product. Covers flat-rate, package, volume, graduated and usage-based (metered) pricing.

Create a product price

POST

https://api.ledgerbee.com/api

/v1/product-prices

x-api-key (header)

OAuth 2.0

Creates a price on a product (productId). currency defaults to the company default currency when omitted.

Required Scope

products-write

Create a product price › Request Body

CreateProductPriceRequest

productId

string · required

The product this price belongs to

Example: 550e8400-e29b-41d4-a716-446655440000

billingPeriodType

string · enum · required

Billing period type. RECURRING requires a Subscription license; USAGE requires Subscription + Metered Products.

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

nickname

string

Optional nickname (e.g. "Monthly")

Example: Monthly

unitAmount

string

Unit amount. Required for FLAT_RATE pricing; for tiered models (PACKAGE/VOLUME/GRADUATED) the amounts live in tiers.

Example: 99.99

billingInterval

string · enum

Billing interval (required unless one-time)

Enum values:

day

week

month

year

billingIntervalCount

number

Billing interval count

Example: 1

currency

string

Currency code (ISO 4217). Defaults to the company default.

Example: DKK

meterId

string

Meter ID (required for USAGE pricing)

CreateProductPriceTierRequest[]

Pricing tiers. Required for tiered models: PACKAGE (exactly 1), VOLUME / GRADUATED (one or more, last tier open-ended). Omit for FLAT_RATE.

Create a product price › Responses

Product price created successfully

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

POST/v1/product-prices

curl https://api.ledgerbee.com/api/v1/product-prices \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Monthly",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "meterId": "meterId",
  "tiers": [
    {
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ]
}'

Example Request Body

{
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Monthly",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "meterId": "meterId",
  "tiers": [
    {
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ]
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Get a product price

GET

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}

x-api-key (header)

OAuth 2.0

Returns a single product price.

Pass ?currency= to get the amount in another ISO 4217 currency — the amount is converted on the fly when no price-history entry exists for that currency.

Required Scope

products-read

Get a product price › path Parameters

priceId

string · required

Product price ID

Get a product price › query Parameters

currency

string

ISO 4217 currency to return the amount in. Converts on the fly when no history entry exists.

Get a product price › Responses

Product price details

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

GET/v1/product-prices/{priceId}

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Delete a product price

DELETE

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}

x-api-key (header)

OAuth 2.0

Deletes a product price. A price that is locked (in use by a subscription or invoice) cannot be deleted.

Required Scope

products-write

Delete a product price › path Parameters

priceId

string · required

Product price ID

Delete a product price › Responses

Product price deleted successfully

No data returned

Update a product price

PATCH

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}

x-api-key (header)

OAuth 2.0

Updates a product price. Only the fields provided in the request are changed.

Required Scope

products-write

Update a product price › path Parameters

priceId

string · required

Product price ID

Update a product price › Request Body

UpdateProductPriceRequest

nickname

string

Optional nickname

Example: Monthly

unitAmount

string

Unit amount for flat-rate pricing

Example: 99.99

billingPeriodType

string · enum

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum

Pricing model

Enum values:

flat_rate

package

volume

graduated

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number

Billing interval count

Example: 1

currency

string

Currency code (ISO 4217)

Example: DKK

status

string · enum

Price status

Enum values:

draft

active

inactive

archived

meterId

string

Meter ID for usage-based pricing

CreateProductPriceTierRequest[]

Pricing tiers

Update a product price › Responses

Product price updated successfully

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

PATCH/v1/product-prices/{priceId}

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "nickname": "Monthly",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "status": "draft",
  "meterId": "meterId",
  "tiers": [
    {
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ]
}'

Example Request Body

{
  "nickname": "Monthly",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "status": "draft",
  "meterId": "meterId",
  "tiers": [
    {
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ]
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Activate a product price

POST

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}/activate

x-api-key (header)

OAuth 2.0

Sets the price's status to active. Returns the price's new state.

Required Scope

products-write

Activate a product price › path Parameters

priceId

string · required

Product price ID

Activate a product price › Responses

Product price activated

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

POST/v1/product-prices/{priceId}/activate

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId/activate \
  --request POST \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Archive a product price

POST

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}/archive

x-api-key (header)

OAuth 2.0

Sets the price's status to archived. Returns the price's new state.

Required Scope

products-write

Archive a product price › path Parameters

priceId

string · required

Product price ID

Archive a product price › Responses

Product price archived

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

POST/v1/product-prices/{priceId}/archive

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId/archive \
  --request POST \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Disable a product price

POST

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}/disable

x-api-key (header)

OAuth 2.0

Sets the price's status to inactive. Returns the price's new state.

Required Scope

products-write

Disable a product price › path Parameters

priceId

string · required

Product price ID

Disable a product price › Responses

Product price disabled (set to inactive)

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

POST/v1/product-prices/{priceId}/disable

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId/disable \
  --request POST \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Set a price as the product default

POST

https://api.ledgerbee.com/api

/v1/product-prices/{priceId}/set-default

x-api-key (header)

OAuth 2.0

Makes this price the default price for its product. Returns the price's new state.

Required Scope

products-write

Set a price as the product default › path Parameters

priceId

string · required

Product price ID

Set a price as the product default › Responses

Product price set as the default for its product

ProductPriceResponse

id

string · required

The unique identifier of the price (use as a line priceId)

Example: 550e8400-e29b-41d4-a716-446655440000

productId

string · required

The product this price belongs to

billingPeriodType

string · enum · required

Billing period type

Enum values:

recurring

usage

one_time

pricingModel

string · enum · required

Pricing model

Enum values:

flat_rate

package

volume

graduated

currency

string · required

Currency of the displayed unitAmount (ISO 4217)

Example: DKK

baseCurrency

string · required

Base currency (source of truth for conversions)

Example: DKK

status

string · enum · required

Price status

Enum values:

draft

active

inactive

archived

isDefault

boolean · required

Whether this is the default price for the product

Example: false

isLocked

boolean · required

Whether the price is locked (in use by a subscription/invoice)

Example: false

vatRatesByZone

object · required

VAT rates by zone (derived from the product group), e.g. { domestic: "25", eu: "0", abroad: "0", domestic_without_vat: "0" }

nickname

string | null

Optional nickname (e.g. "Monthly")

unitAmount

string | null

Unit amount for flat-rate pricing in currency

Example: 99.99

billingInterval

string | null · enum

Billing interval (null for one-time)

Enum values:

day

week

month

year

billingIntervalCount

number | null

Billing interval count

Example: 1

availableCurrencies

string[]

Currencies with a price-history entry

meterId

string | null

Meter ID for usage-based pricing

ProductPriceTierResponse[]

Pricing tiers (package/volume/graduated)

POST/v1/product-prices/{priceId}/set-default

curl https://api.ledgerbee.com/api/v1/product-prices/:priceId/set-default \
  --request POST \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "productId": "productId",
  "nickname": "nickname",
  "unitAmount": "99.99",
  "billingPeriodType": "recurring",
  "pricingModel": "flat_rate",
  "billingInterval": "day",
  "billingIntervalCount": 1,
  "currency": "DKK",
  "baseCurrency": "DKK",
  "availableCurrencies": [
    "string"
  ],
  "status": "draft",
  "isDefault": false,
  "isLocked": false,
  "meterId": "meterId",
  "tiers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fromQuantity": 1,
      "toQuantity": 10,
      "unitAmount": "99.99",
      "flatFee": "10.00"
    }
  ],
  "vatRatesByZone": {}
}

json

application/json

Product Groups Products