BillKit/Docs Console
Prices

Create price

Create a price, which is what a customer actually buys.

POST/v1/prices
Operation create_price · Scope prices:write · Spec snapshot 2026-09-13

Parameters

ParameterDescription
intervalenumrequiredOne of month, year.
product_idstringrequiredAt most 64 characters.
amount_centsinteger | nulloptionalMinimum 0.
billing_schemeenumoptionalOne of per_unit, tiered. Defaults to "per_unit".
currencystringoptionalDefaults to "EUR". At most 3 characters.
metadataobject | nulloptionalAt most 50 keys.
payment_methodsarray of enumoptionalDefaults to ["creditcard"].
refund_on_cancelenumoptionalWhat a cancellation refunds, against the most recent charge. 'none' (default) refunds nothing. 'full' refunds the whole charge and ends access immediately. 'prorated' refunds the unused part of the current period and also ends access. Both are still bounded by the refund window below. Metered prices must leave this at 'none': ending access mid-period would strand usage that has not been billed yet. One of none, full, prorated. Defaults to "none".
refund_window_initial_daysinteger | nulloptionalBetween 0 and 365.
refund_window_renewal_daysinteger | nulloptionalBetween 0 and 365.
tax_behaviorenumoptionalOne of inclusive, exclusive, unspecified. Defaults to "unspecified".
tiersarray of object | nulloptionalNo description in the spec.
tiers_modeenum | nulloptionalOne of graduated, volume.
trial_daysintegeroptionalDefaults to 0. Between 0 and 90.
trial_verification_centsintegeroptionalDefaults to 100. Minimum 0.
unit_amount_decimalstring | nulloptionalPer-unit rate in minor units with up to 12 decimal places, as a string ('0.02' means 0.02 cents). Metered prices only, and mutually exclusive with amount_cents. Always a string: a JSON number cannot hold this value exactly. At most 32 characters.
usage_typeenumoptionalOne of licensed, metered. Defaults to "licensed".

Returns

Returns a PriceResponse object.

Errors

Status Cause
401 Missing or invalid API key.
403 Key is missing the prices:write scope.
422 Validation Error
429 Rate limited. Back off and retry.
Request · curl 
curl -X POST https://api.billkit.eu/v1/prices \
  -H "Authorization: Bearer $BILLKIT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interval":"month","product_id":"prod_9XKp2vQ1"}'
Request body · every field 
{
  "amount_cents": 1900,
  "billing_scheme": "per_unit",
  "currency": "EUR",
  "interval": "month",
  "metadata": {
    "key": "value"
  },
  "payment_methods": [
    "creditcard"
  ],
  "product_id": "prod_9XKp2vQ1",
  "refund_on_cancel": "none",
  "refund_window_initial_days": 0,
  "refund_window_renewal_days": 0,
  "tax_behavior": "unspecified",
  "tiers": [
    {
      "flat_amount": 1900,
      "unit_amount": 1900,
      "unit_amount_decimal": "string",
      "up_to": "string"
    }
  ],
  "tiers_mode": "graduated",
  "trial_days": 0,
  "trial_verification_cents": 100,
  "unit_amount_decimal": "string",
  "usage_type": "licensed"
}
Response · 200 OK 
{
  "active": false,
  "amount_cents": 1900,
  "billing_scheme": "string",
  "created": 1789392000,
  "currency": "EUR",
  "id": "price_9XKp2vQ1",
  "interval": "string",
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "object": "price",
  "payment_methods": [
    "string"
  ],
  "product_id": "prod_9XKp2vQ1",
  "product_name": "Ada Lovelace",
  "refund_on_cancel": "none",
  "refund_window_initial_days": 0,
  "refund_window_renewal_days": 0,
  "tax_behavior": "string",
  "tiers": [
    {
      "flat_amount": 1900,
      "unit_amount_decimal": "string",
      "up_to": 0
    }
  ],
  "tiers_mode": "string",
  "trial_days": 0,
  "trial_verification_cents": 1900,
  "unit_amount_decimal": "string",
  "usage_type": "string"
}