> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Plan Charges > List the usage charges attached to a plan, with each charge's billable metric joined in. Returns every usage charge configured on a plan — one per billable metric — with the metric embedded so a consumer can render pricing without a second lookup. Charges are the usage-priced half of a plan; flat recurring prices stay on the plan itself (see [Get a Plan](/api-reference/plans/get)). To replace the set use [Set Plan Charges](/api-reference/billing/set-charges); to preview what a charge set would bill against sample usage use [Simulate Charges](/api-reference/billing/simulate-charges). Usage is billed in arrears at period close unless a charge sets `pay_in_advance`, in which case each event is rated at ingestion and captured as an unbilled charge for the next invoice. ## Parameters | Parameter | Type | Required | Description | | --------- | ------------- | -------- | ------------------------------------------ | | `id` | string (UUID) | Yes | Plan ID (path). Must belong to your tenant | ## Example Request ```bash theme={null} curl https://api.recurso.dev/v1/plans/3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14/charges \ -H "Authorization: Bearer $API_KEY" ``` ## Response An empty plan returns `{"data": []}`. ```json theme={null} { "data": [ { "id": "b4c8d1e2-6f3a-4b9c-8d7e-1a2f3c4d5e60", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "plan_id": "3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14", "metric_id": "7d2e9f10-3c4b-4a5d-9e8f-0b1c2d3e4f51", "charge_model": "graduated", "amounts": { "INR": { "tiers": [ { "up_to": 100000, "unit_amount": "0.0050" }, { "up_to": null, "unit_amount": "0.0035" } ] } }, "created_at": "2026-05-12T10:30:00Z", "updated_at": "2026-05-12T10:30:00Z", "metric": { "id": "7d2e9f10-3c4b-4a5d-9e8f-0b1c2d3e4f51", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "name": "API calls", "code": "api_calls", "aggregation_type": "sum", "created_at": "2026-05-01T08:00:00Z", "updated_at": "2026-05-01T08:00:00Z" } }, { "id": "c5d9e2f3-7a4b-4c0d-9e8f-2b3a4c5d6e71", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "plan_id": "3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14", "metric_id": "8e3fa021-4d5c-4b6e-8f9a-1c2d3e4f5a62", "charge_model": "per_unit", "amounts": { "INR": { "unit_amount": "0.2500" } }, "pay_in_advance": true, "hsn_code": "998314", "created_at": "2026-05-12T10:30:00Z", "updated_at": "2026-06-02T14:05:00Z", "metric": { "id": "8e3fa021-4d5c-4b6e-8f9a-1c2d3e4f5a62", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "name": "Outbound emails", "code": "emails_sent", "aggregation_type": "count", "created_at": "2026-05-01T08:05:00Z", "updated_at": "2026-05-01T08:05:00Z" } } ] } ``` ## Fields | Field | Type | Description | | --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string (UUID) | Charge ID | | `tenant_id` | string (UUID) | Owning tenant | | `plan_id` | string (UUID) | The plan the charge is attached to | | `metric_id` | string (UUID) | The billable metric this charge prices | | `charge_model` | string | `per_unit`, `graduated`, `volume`, `package`, `percentage`, `graduated_percentage`, or `dynamic` | | `amounts` | object | Pricing keyed by ISO currency code; the invoice currency selects the entry at rating time. Which keys are present depends on `charge_model` (see below) | | `filter_key` | string | Event property this charge prices dimensionally; omitted when unfiltered | | `filters[]` | array | One `{value, amounts}` band per priced property value; events matching none use `amounts` | | `pay_in_advance` | boolean | Rate per event at ingestion instead of at period close; omitted when `false`. Only `per_unit`, `percentage` and `dynamic` charges may set it | | `hsn_code` | string | HSN/SAC code for the charge's invoice lines; omitted when it falls back to the plan's code, then the tenant's | | `created_at` / `updated_at` | string (RFC 3339) | Timestamps | | `metric` | object | The joined billable metric: `id`, `tenant_id`, `name`, `code` (equals the event `dimension` it aggregates), `aggregation_type`, optional `field_name` / `expression`, timestamps | ### `amounts` by charge model | Key | Type | Used by | Description | | --------------------------- | ------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unit_amount` | string | `per_unit` | Per-unit rate as a decimal string in **major** currency units (e.g. `"0.0035"`), so sub-minor-unit rates are exact | | `package_amount` | integer | `package` | Price per bundle, minor units | | `package_size` | integer | `package` | Units per bundle; partial bundles round up | | `tiers[]` | array | `graduated`, `volume`, `graduated_percentage` | Price bands: `up_to` (inclusive upper bound, `null` = unbounded last tier), `unit_amount` (decimal string, major units), `rate` (percent string, `graduated_percentage` only), `flat_amount` (minor units, added once when any unit lands in the tier) | | `rate` | string | `percentage` | Percent applied to the monetary base, decimal string (e.g. `"2.5"`) | | `fixed_amount` | integer | `percentage` | Flat fee in minor units added after the percentage | | `free_units` | integer | `percentage` | Base units exempt from the percentage, deducted first | | `min_amount` / `max_amount` | integer | `percentage` | Floor / cap on the line in minor units; `0` = none | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ------------------------------------ | ------------------------------------------------------------ | | `400` | `validation_failed` | `id` is not a valid UUID | Pass the plan's UUID | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `404` | `not_found` | No plan with that ID in your tenant | Check the ID against [List Plans](/api-reference/plans/list) | | `500` | `internal_error` | Loading the charges failed | Retry; contact support if it persists | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/plans/{id}/charges openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/plans/{id}/charges: get: tags: - Metering summary: List a plan's usage charges operationId: getPlanCharges parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: The plan's charges with metrics joined content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Charge' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: Charge: type: object description: >- Usage pricing for one billable metric on a plan. Usage is billed in arrears at period close; flat plan prices stay on the plan. properties: id: type: string format: uuid plan_id: type: string format: uuid metric_id: type: string format: uuid charge_model: type: string enum: - per_unit - graduated - volume - package - percentage - graduated_percentage - dynamic amounts: type: object additionalProperties: $ref: '#/components/schemas/ChargeAmounts' description: Pricing per ISO currency code. filter_key: type: string description: >- (A4) An event property this charge prices dimensionally; empty = unfiltered. Each `filters` entry prices one value of this property; events matching none use `amounts` (the default). filters: type: array items: $ref: '#/components/schemas/ChargeFilterValue' pay_in_advance: type: boolean description: >- Rate this charge per usage event at ingestion time (captured as an unbilled charge, folded onto the next invoice) instead of at period close. Only per_unit/percentage/dynamic may set it. hsn_code: type: string metric: $ref: '#/components/schemas/BillableMetric' ChargeAmounts: type: object description: Pricing properties for one currency; fields depend on the charge model. properties: unit_amount: type: string description: (per_unit) decimal-string rate in MAJOR currency units. package_amount: type: integer format: int64 description: (package) price in minor units per bundle. package_size: type: integer format: int64 description: (package) units per bundle; partial bundles round up. tiers: type: array items: $ref: '#/components/schemas/ChargeTier' description: (graduated/volume) price bands. rate: type: string description: (percentage) percent applied to the base, decimal string e.g. "2.5". fixed_amount: type: integer format: int64 description: (percentage) flat fee in minor units added after the percentage. free_units: type: integer format: int64 description: (percentage) base units exempt from the percentage, deducted first. min_amount: type: integer format: int64 description: (percentage) floor on the line in minor units; 0 = no floor. max_amount: type: integer format: int64 description: (percentage) cap on the line in minor units; 0 = no cap. ChargeFilterValue: type: object required: - value - amounts properties: value: type: string description: The property value this band prices. amounts: type: object additionalProperties: $ref: '#/components/schemas/ChargeAmounts' BillableMetric: type: object description: >- A tenant-defined meter over usage events; `code` equals the event `dimension` it aggregates and is unique per tenant. properties: id: type: string format: uuid tenant_id: type: string format: uuid name: type: string code: type: string aggregation_type: type: string enum: - count - sum - max - unique - latest - percentile - custom - weighted_sum field_name: type: string description: >- Event property counted by `unique`, or the percentile 1-99 for `percentile`. expression: type: string description: > Sandboxed per-event formula for the `custom` aggregation (e.g. `quantity * properties.multiplier`); its results are summed over the period. Empty for every other aggregation. created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. ChargeTier: type: object required: - up_to properties: up_to: type: - integer - 'null' format: int64 description: Inclusive upper unit bound; null = unbounded (last tier only). unit_amount: type: string description: >- (graduated/volume) per-unit rate as a decimal string in MAJOR currency units (e.g. "0.0035"). rate: type: string description: >- (graduated_percentage) percent applied to this band of the base, decimal string e.g. "2.5". flat_amount: type: integer format: int64 description: Minor units, added once when any unit lands in the tier. responses: Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````