> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Plan Meter
> Updates the included credits, pricing strategy, unit price or per-country prices of a meter attached to a plan.
**Enabled per organization**
Usage-based billing must be enabled for your organization before these endpoints accept requests. Contact your Yuno account manager to enable it. Requests from an organization where it is not enabled return `403 PRODUCT_NOT_ENABLED`.
Send at least one of `credits`, `pricing_strategy`, `price_per_credit`, `country_prices`. The same currency rules as [Attach Meter to Plan](/reference/meters/attach-meter-to-plan) apply. If the meter has been archived (`INACTIVE`) the metered price is frozen and this call returns `400 PLAN_METER_NOT_FOUND` until the meter is reactivated.
**`PACKAGE`/`TIERED` config is attach-time only**
`package_size`, `package_price`, `package_country_prices` and `tiers` cannot be sent to this endpoint — any request containing one of them is rejected with `400 PLAN_METER_PRICING_CONFIG_UNSUPPORTED`, regardless of the metered price's current `pricing_strategy`. Switching `pricing_strategy` itself is validated against the metered price's existing config for the target strategy; an unsupported switch is rejected rather than silently applied. To change a `PACKAGE`/`TIERED` config, attach a new meter instead — see the [Usage-Based Billing guide](/docs/payment-features/subscriptions/usage-based-billing#pricing-a-meter-on-a-plan).
There is no detach endpoint. To stop billing a meter, archive it with [Update Meter](/reference/meters/update-meter) (`status: INACTIVE`), or set `credits` high enough that no overage is billed.
Refer to [Meter Error Codes](/reference/meters/meter-error-codes) for the possible error outcomes.
## OpenAPI
````yaml openapi/meters/update-plan-meter.json PATCH /subscriptions/plans/{plan_id}/meters/{meter_id}
openapi: 3.1.0
info:
title: meters
version: 1.0.0
servers:
- url: https://api-sandbox.y.uno/v1
- url: https://api.eu.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/subscriptions/plans/{plan_id}/meters/{meter_id}:
patch:
summary: Update Plan Meter
description: >-
Usage-based billing must be enabled for your organization before this
endpoint accepts requests (otherwise `403 PRODUCT_NOT_ENABLED`). Updates
a metered price already attached to a plan: included `credits`,
`pricing_strategy`, `price_per_credit` and `country_prices`. Send at
least one field. The change applies to usage rated from the
subscription's next billing cycle onward. `package_size`,
`package_price`, `package_country_prices` and `tiers` cannot be sent
here — any request containing one is rejected with `400
PLAN_METER_PRICING_CONFIG_UNSUPPORTED`; `PACKAGE`/`TIERED` config is
attach-time only, and switching `pricing_strategy` is validated against
the metered price's config for the target strategy. If the meter is
`INACTIVE` the metered price is frozen and this call returns `400
PLAN_METER_NOT_FOUND`. To stop billing a meter on a plan, archive the
meter (Update Meter with `status: INACTIVE`) — there is no detach
endpoint.
operationId: update-plan-meter
parameters:
- in: header
name: X-Account-Code
required: true
schema:
type: string
description: >-
The `account_id` found in your [Yuno
Dashboard](https://dashboard.y.uno/developers) (UUID). Required —
omitting it returns `400 BAD_REQUEST` ("Invalid x-account-code
header.").
- name: plan_id
in: path
required: true
description: The unique identifier of the plan.
schema:
type: string
- name: meter_id
in: path
required: true
description: The unique identifier of the meter attached to the plan.
schema:
type: string
- in: header
name: X-Idempotency-Key
required: true
schema:
type: string
description: >-
Unique identifier used in HTTP headers to ensure that a request is
processed only once, even if it is retried due to network issues or
timeouts. Optional, as on the rest of the Yuno API.
requestBody:
content:
application/json:
schema:
type: object
properties:
credits:
type: number
format: float
description: >-
Units included in the plan per billing cycle — the allowance
a subscriber can consume before any usage is billed. Must be
>= 0. `0` means every unit is billed.
pricing_strategy:
type: string
enum:
- PER_UNIT
- PACKAGE
- TIERED
description: >-
How usage beyond `credits` is priced: `PER_UNIT` (billable
units × `price_per_credit`), `PACKAGE` (bundles of N units,
partial bundle counts as a full one) or `TIERED` (graduated
tiers, each band at its own rate).
price_per_credit:
type: object
required:
- currency
- value
properties:
currency:
type: string
description: >-
MAX 3; MIN 3. Must equal the plan's `base_amount`
currency, else `400 INVALID_PARAMETERS`.
value:
type: number
format: float
description: >-
Price per unit beyond the included credits (multiple of
0.0001). Optional only when the plan's base currency is
`USD` and the meter has a `default_price` — the meter's
default then applies and the metered price is returned
with `price_per_credit: null`. Required otherwise.
country_prices:
type: array
description: >-
Optional explicit per-country price per unit. One entry per
country — a repeated country is rejected with `400
INVALID_PARAMETERS`. A country not listed falls back to
`price_per_credit`.
items:
type: object
required:
- country
- amount
properties:
country:
type: string
description: >-
MAX 2; MIN 2; [ISO
3166-1](/reference/country-reference).
amount:
type: object
required:
- currency
- value
properties:
currency:
type: string
description: >-
MAX 3; MIN 3; [ISO
4217](/reference/country-reference).
value:
type: number
format: float
description: Multiple of 0.0001.
examples:
Raise the allowance and lower the unit price:
value:
credits: 250
price_per_credit:
currency: USD
value: 0.04
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
id: 77777777-7777-7777-7777-777777777777
plan_id: 00000000-0000-4000-8000-000000000001
meter_id: 66666666-6666-6666-6666-666666666666
credits: 250
pricing_strategy: PER_UNIT
price_per_credit:
currency: USD
value: 0.04
country_prices:
- country: US
amount:
currency: USD
value: 0.06
created_at: '2026-08-18T09:00:04.000000Z'
updated_at: '2026-08-18T12:15:00.000000Z'
schema:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the metered price (the plan-meter
relation).
plan_id:
type: string
meter_id:
type: string
credits:
type: number
description: Units included in the plan per billing cycle.
pricing_strategy:
type: string
enum:
- PER_UNIT
- PACKAGE
- TIERED
price_per_credit:
type: object
nullable: true
description: >-
`null` when inherited from the meter's `default_price`
(USD plans).
properties:
currency:
type: string
value:
type: number
country_prices:
type: array
items:
type: object
properties:
country:
type: string
amount:
type: object
properties:
currency:
type: string
value:
type: number
created_at:
type: string
description: Set by Yuno on creation.
updated_at:
type: string
description: Set by Yuno on every update.
'400':
description: '400'
content:
application/json:
examples:
Empty body:
summary: Empty body
value:
code: INVALID_PARAMETERS
messages:
- At least one field must be provided
Currency mismatch:
summary: Currency mismatch
value:
code: INVALID_PARAMETERS
messages:
- >-
The price_per_credit currency must match the plan base
currency
Missing price on non-USD plan:
summary: Missing price on non-USD plan
value:
code: INVALID_PARAMETERS
messages:
- >-
A price_per_credit is required when the plan base
currency is not USD
Missing price and no default:
summary: Missing price and no default
value:
code: INVALID_PARAMETERS
messages:
- >-
A price_per_credit is required when the meter has no
default_price
Negative credits:
summary: Negative credits
value:
code: INVALID_PARAMETERS
messages:
- The meter credits must be greater than or equal to 0
Invalid strategy:
summary: Invalid strategy
value:
code: INVALID_PARAMETERS
messages:
- >-
The meter pricing_strategy must be one of PER_UNIT,
PACKAGE, TIERED
Duplicate country:
summary: Duplicate country
value:
code: INVALID_PARAMETERS
messages:
- The country_prices must not contain duplicate countries
Unknown or inactive meter:
summary: Unknown or inactive meter
value:
code: METER_NOT_FOUND
messages:
- >-
The meter does not exist, is inactive or is not linked
to this account.
Unknown plan:
summary: Unknown plan
value:
code: PLAN_NOT_FOUND
messages:
- >-
The plan does not exist or is not linked to this
account.
Meter not attached to the plan, or inactive:
summary: Meter not attached to the plan, or inactive
value:
code: PLAN_METER_NOT_FOUND
messages:
- >-
The meter 66666666-6666-6666-6666-666666666666 is not
assigned to this plan
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
'403':
description: '403'
content:
application/json:
examples:
Product not enabled:
summary: Product not enabled
value:
code: PRODUCT_NOT_ENABLED
messages:
- Usage-based billing is not enabled for this organization
schema:
type: object
properties:
code:
type: string
example: PRODUCT_NOT_ENABLED
messages:
type: array
items:
type: string
'404':
description: '404'
content:
application/json:
examples:
PLAN METER NOT FOUND:
value:
code: PLAN_METER_NOT_FOUND
messages:
- This meter is not attached to this plan.
summary: >-
The meter exists and the plan exists, but the meter is not
attached to that plan.
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````