BillKitPrices
Create price
Create a price for a product: the amount, currency and interval a customer buys.
POST/v1/prices
Parameters
| Parameter | Description |
|---|---|
| intervalenumrequired | How often the price is charged. Metered prices must use month. One of month, year. |
| product_idstringrequired | The product this price belongs to. It must be active. At most 64 characters. |
| amount_centsinteger | nulloptional | Amount charged each period, in minor units of currency. On a metered price it is the per-unit rate. Must be positive. Send exactly one of amount_cents and unit_amount_decimal, or neither on a tiered price. Between 0 and 99999999. |
| billing_schemeenumoptional | per_unit multiplies one rate by the quantity. tiered prices the quantity by tiers and is for metered prices only. One of per_unit, tiered. Defaults to "per_unit". |
| currencystringoptional | Three-letter ISO 4217 currency code, stored uppercase. Must be one of the currencies enabled for your account. Defaults to "EUR". At most 3 characters. |
| metadataobject | nulloptional | Key-value pairs stored on the price and returned with it. At most 50 keys. |
| payment_methodsarray of enum | nulloptional | Payment methods offered at checkout for this price, overriding your account's. Leave it out to follow your account: the price then offers every method you have on in Mollie and have not switched off in your account settings. Must include at least one method that can make the first payment (not only directdebit). |
| refund_on_cancelenumoptional | What 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 | nulloptional | Days after the first charge (or a plan change onto this price) during which it can be refunded. 0 disables refunds of that charge. Null uses the default: 7 days on a monthly price, 30 on a yearly one. Between 0 and 365. |
| refund_window_renewal_daysinteger | nulloptional | Days after a renewal charge during which it can be refunded. 0 disables refunds of renewals. Null uses the default of 3 days. Between 0 and 365. |
| tax_behaviorenumoptional | Whether amount_cents includes VAT (inclusive) or has it added on top (exclusive). unspecified follows the inclusive setting of the tax rate for the customer's country, and is inclusive when there is none. One of inclusive, exclusive, unspecified. Defaults to "unspecified". |
| tiersarray of object | nulloptional | The pricing bands, in increasing order. Required when billing_scheme is tiered, refused otherwise. |
| tiers_modeenum | nulloptional | Required when billing_scheme is tiered, refused otherwise. graduated prices the units inside each band at that band's rate; volume picks one band from the total quantity and prices every unit at it. One of graduated, volume. |
| trial_daysintegeroptional | Length of the free trial a new subscription starts with, in days. Metered prices take 0. Defaults to 0. Between 0 and 90. |
| trial_verification_centsintegeroptional | Amount in minor units charged at checkout instead of the price when the checkout only sets up the payment mandate: during a trial, and on every metered price. Defaults to 100. Between 0 and 99999999. |
| unit_amount_decimalstring | nulloptional | Per-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_typeenumoptional | licensed charges amount_cents every period. metered bills reported usage at the end of each monthly period, and checkout charges only trial_verification_cents. One of licensed, metered. Defaults to "licensed". |
Returns
Returns a PriceResponse object.
Errors
| Status | Cause |
|---|---|
| 400 | The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it. |
| 401 | No credential, or one that does not authenticate. |
| 402 | The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused). |
| 403 | Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the prices:write scope. |
| 404 | No such object in this account and mode. |
| 409 | Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending). |
| 413 | The request body is larger than the API accepts. |
| 429 | Rate limited. Retry-After says when to try again. |
| 500 | Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key. |
| 502 | The payment provider failed or did not answer. |
| 503 | Temporarily unable to serve. reason says whether the request was attempted. |
Other prices operations
- List prices GET /v1/prices
- Get price GET /v1/prices/{price_id}
- Update price POST /v1/prices/{price_id}