BillKit/DocsConsole
Prices

Update price

Archive a price, restore it, or change its forward-looking settings.

POST/v1/prices/{price_id}
Operation update_price·Scope prices:write·OpenAPI v1.1.0

Parameters

ParameterDescription
price_idstring · pathrequiredId of the price, which starts price_.
activebooleanoptionalfalse archives the price: new checkouts and plan changes cannot use it, and existing subscriptions keep renewing on it. true restores it.
metadataobjectoptionalReplaces the stored metadata whole. Send {} to empty it. At most 50 keys.
payment_methodsarray of enum | nulloptionalPayment methods offered at checkout for this price, overriding your account's. Send null to go back to following your account. Must include at least one method that can make the first payment (not only directdebit).
refund_on_cancelenumoptionalWhat a cancellation refunds against the most recent charge: none, full or prorated. Applies to customers already on the price. Metered prices must keep none. One of none, full, prorated.
refund_window_initial_daysinteger | nulloptionalRefund window for the first charge, in days. 0 disables refunds of that charge; null goes back to the default (7 days monthly, 30 yearly). Between 0 and 365.
refund_window_renewal_daysinteger | nulloptionalRefund window for renewal charges, in days. 0 disables refunds of renewals; null goes back to the default of 3 days. Between 0 and 365.
tax_behaviorenumoptionalCan be set only while the price's tax_behavior is unspecified, and not changed after. One of inclusive, exclusive.

Returns

Returns a PriceResponse object.

Errors

StatusCause
400The 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.
401No credential, or one that does not authenticate.
402The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused).
403Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the prices:write scope.
404No such object in this account and mode.
409Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending).
413The request body is larger than the API accepts.
429Rate limited. Retry-After says when to try again.
500Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key.
502The payment provider failed or did not answer.
503Temporarily unable to serve. reason says whether the request was attempted.
Request · curl
curl -X POST https://api.billkit.eu/v1/prices/price_9XKp2vQ1 \
  -H "Authorization: Bearer $BILLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body · every field
{
  "active": false,
  "metadata": {
    "key": "value"
  },
  "payment_methods": [
    "creditcard"
  ],
  "refund_on_cancel": "none",
  "refund_window_initial_days": 0,
  "refund_window_renewal_days": 0,
  "tax_behavior": "inclusive"
}
Response · 200 OK
{
  "active": false,
  "amount_cents": 1900,
  "billing_scheme": "per_unit",
  "created": 1789392000,
  "currency": "EUR",
  "id": "price_9XKp2vQ1",
  "interval": "month",
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "object": "price",
  "payment_methods": [
    "creditcard"
  ],
  "payment_methods_from_account": false,
  "product_id": "prod_9XKp2vQ1",
  "product_name": "Ada Lovelace",
  "refund_on_cancel": "none",
  "refund_window_initial_days": 0,
  "refund_window_renewal_days": 0,
  "tax_behavior": "inclusive",
  "tiers": [
    {
      "flat_amount_cents": 1900,
      "unit_amount_decimal": "string",
      "up_to": 0
    }
  ],
  "tiers_mode": "graduated",
  "trial_days": 0,
  "trial_verification_cents": 1900,
  "unit_amount_decimal": "string",
  "usage_type": "licensed"
}