> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a Billing Package > Create a billing package for period-based charges. Supports two types — `volume` (transaction count-based) and `maintenance` (per-account fixed fee). ## OpenAPI ````yaml /en/openapi/v3-current/fees-engine.yaml post /v1/billing-packages openapi: 3.1.0 info: title: Fees Engine description: '' version: 3.2.0 servers: - url: https://fees.sandbox.lerian.net security: [] tags: - name: Fees Engine paths: /v1/billing-packages: post: tags: - Billing Packages API summary: Create a Billing Package description: >- Create a billing package for period-based charges. Supports two types — `volume` (transaction count-based) and `maintenance` (per-account fixed fee). parameters: - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBillingPackageRequest' examples: volume: summary: Volume billing package value: label: Pix Send Monthly Billing description: Monthly volume billing for Pix transactions ledgerId: ldg_01HZ... type: volume enable: true eventFilter: transactionRoute: pix-send status: APPROVED pricingModel: tiered tiers: - minQuantity: 1 maxQuantity: 100 unitPrice: '0.50' - minQuantity: 101 maxQuantity: 500 unitPrice: '0.35' - minQuantity: 501 maxQuantity: null unitPrice: '0.20' freeQuota: 10 discountTiers: - minQuantity: 200 discountPercentage: '5.00' - minQuantity: 400 discountPercentage: '10.00' countMode: perAccount assetCode: BRL debitAccountAlias: client-wallet creditAccountAlias: fees-revenue maintenance: summary: Maintenance billing package value: label: PF Account Maintenance description: Monthly maintenance fee for active PF accounts ledgerId: ldg_01HZ... type: maintenance enable: true feeAmount: '9.90' assetCode: BRL maintenanceCreditAccount: fees-maintenance-pf accountTarget: segmentId: seg_pf_01HZ... responses: '201': description: Billing package created successfully. content: application/json: schema: $ref: '#/components/schemas/BillingPackageResponse' example: id: bpkg_01HZ... label: Pix Send Monthly Billing type: volume enable: true organizationId: org_01HZ... ledgerId: ldg_01HZ... createdAt: '2026-03-01T00:00:00Z' updatedAt: '2026-03-01T00:00:00Z' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Error0001: $ref: '#/components/examples/Error0001' Error0002: $ref: '#/components/examples/Error0002' Error0019: $ref: '#/components/examples/Error0019' Error0020: $ref: '#/components/examples/Error0020' Error0041: $ref: '#/components/examples/Error0041' Error0053: $ref: '#/components/examples/Error0053' Error0054: $ref: '#/components/examples/Error0054' Error0055: $ref: '#/components/examples/Error0055' Error0056: $ref: '#/components/examples/Error0056' Error0057: $ref: '#/components/examples/Error0057' Error0058: $ref: '#/components/examples/Error0058' Error0064: $ref: '#/components/examples/Error0064' Error0065: $ref: '#/components/examples/Error0065' Error0067: $ref: '#/components/examples/Error0067' Error0069: $ref: '#/components/examples/Error0069' Error0070: $ref: '#/components/examples/Error0070' '409': description: Conflict — a billing package with the same key already exists. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/Error' examples: Error0004: $ref: '#/components/examples/Error0004' security: [] components: parameters: XOrganizationId: name: X-Organization-Id in: header description: The unique identifier of the Organization associated with the request. required: true schema: type: string example: 019c96a0-0a98-7287-9a31-786e0809c769 Authorization: name: Authorization in: header description: >- The authorization token in the 'Bearer ' format. **Important:** This header is required if your environment has Access Manager enabled. For more information, refer to the [Access Manager](/en/access-manager) documentation. required: false schema: type: string ContentType: name: Content-Type in: header description: The type of media of the resource. Must be `application/json`. required: true schema: type: string example: application/json schemas: CreateBillingPackageRequest: description: > Request body to create a billing package. The set of required fields depends on `type`. - `volume` packages require `eventFilter`, `pricingModel`, at least one `tiers` entry, `assetCode`, `debitAccountAlias`, and `creditAccountAlias`. - `maintenance` packages require `feeAmount`, `assetCode`, `maintenanceCreditAccount`, and `accountTarget`. `enable` is optional; when omitted, the service defaults it to `true`. type: object required: - label - ledgerId - type properties: label: type: string description: Name of the billing package. description: type: string description: Optional description. ledgerId: type: string description: Ledger that records the billing transactions. type: type: string enum: - volume - maintenance description: 'Billing type: `volume` or `maintenance`.' enable: type: boolean description: >- Whether the package is active. Optional. Defaults to `true` when omitted. eventFilter: type: object description: (Volume only) Filter for which transactions to count. required: - transactionRoute - status properties: transactionRoute: type: string description: Transaction route that the package is associated with. status: type: string description: Transaction status to count (for example, `APPROVED`). pricingModel: type: string enum: - tiered - fixed description: (Volume only) Pricing model. tiers: type: array minItems: 1 description: >- (Volume only) Quantity ranges and unit prices. At least one tier is required. items: type: object required: - minQuantity - unitPrice properties: minQuantity: type: integer description: Minimum quantity (inclusive) for which the tier applies. maxQuantity: type: integer nullable: true description: >- Maximum quantity (inclusive) for the tier, or `null` for an open-ended upper bound. unitPrice: type: string description: >- Unit price applied to transactions inside the tier. Decimal value as a string (e.g., `"0.50"`). freeQuota: type: integer description: (Volume only) Transactions exempt before charging. discountTiers: type: array description: (Volume only) Progressive discount thresholds. items: type: object properties: minQuantity: type: integer discountPercentage: type: string description: Decimal value as a string (e.g., `"5.00"`). countMode: type: string enum: - perRoute - perAccount description: (Volume only) How transactions are grouped. assetCode: type: string description: Currency code (e.g., BRL). debitAccountAlias: type: string description: (Volume only) Account to debit. creditAccountAlias: type: string description: (Volume only) Account to credit. feeAmount: type: string description: >- (Maintenance only) Fixed fee per active account. Decimal value as a string (e.g., `"9.90"`). maintenanceCreditAccount: type: string description: (Maintenance only) Account that receives the fee. accountTarget: type: object description: >- (Maintenance only) Target accounts. Provide exactly one of `segmentId`, `portfolioId`, or `aliases`. oneOf: - required: - segmentId - required: - portfolioId - required: - aliases properties: segmentId: type: string description: Segment whose accounts are billed. portfolioId: type: string description: Portfolio whose accounts are billed. aliases: type: array description: Explicit list of account aliases to bill. minItems: 1 items: type: string oneOf: - title: Volume billing package description: Required fields for `type = volume`. properties: type: const: volume required: - eventFilter - pricingModel - tiers - assetCode - debitAccountAlias - creditAccountAlias - title: Maintenance billing package description: Required fields for `type = maintenance`. properties: type: const: maintenance required: - feeAmount - assetCode - maintenanceCreditAccount - accountTarget BillingPackageResponse: type: object properties: id: type: string description: Unique identifier of the billing package. label: type: string description: type: string type: type: string enum: - volume - maintenance enable: type: boolean organizationId: type: string ledgerId: type: string eventFilter: type: object properties: transactionRoute: type: string status: type: string pricingModel: type: string tiers: type: array items: type: object properties: minQuantity: type: integer maxQuantity: type: integer nullable: true unitPrice: type: string freeQuota: type: integer discountTiers: type: array items: type: object properties: minQuantity: type: integer discountPercentage: type: string countMode: type: string assetCode: type: string debitAccountAlias: type: string creditAccountAlias: type: string feeAmount: type: string maintenanceCreditAccount: type: string accountTarget: type: object properties: segmentId: type: string portfolioId: type: string aliases: type: array items: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time deletedAt: type: string format: date-time nullable: true Error: type: object properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. required: - code - title - message description: The response message error. examples: Error0001: summary: Unexpected fields in the request value: code: FEE-0001 title: Unexpected fields in the request message: >- The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. Error0002: summary: Missing fields in request value: code: FEE-0002 title: Missing fields in request message: >- Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. Error0019: summary: Invalid header parameter value: code: FEE-0019 title: Invalid header parameter message: >- One or more headers parameters are in an incorrect format. Please check the following parameters and ensure they meet the required format before trying again. Error0020: summary: Missing header value: code: FEE-0020 title: Missing header message: >- Headers parameters is required. Please check the following header parameters %v and ensure they are passing the values correctly. Error0041: summary: Unmarshalling error value: code: FEE-0041 title: Unmarshalling error message: 'Invalid value for field ''%s'': expected type ''%s'', but got ''%s''.' Error0053: summary: Invalid billing type value: code: FEE-0053 title: Invalid billing type message: The type field must be `volume` or `maintenance`. Error0054: summary: Missing volume fields value: code: FEE-0054 title: Missing volume fields message: >- Volume billing packages require: eventFilter, pricingModel, tiers, assetCode, debitAccountAlias, and creditAccountAlias. Error0055: summary: Missing maintenance fields value: code: FEE-0055 title: Missing maintenance fields message: >- Maintenance billing packages require: feeAmount, assetCode, maintenanceCreditAccount, and accountTarget. Error0056: summary: Invalid pricing model value: code: FEE-0056 title: Invalid pricing model message: The pricingModel field must be `tiered` or `fixed`. Error0057: summary: Invalid pricing tier value: code: FEE-0057 title: Invalid pricing tier message: >- Tiers must not overlap and must have valid minQuantity, maxQuantity, and positive unitPrice. Error0058: summary: Billing route overlap value: code: FEE-0058 title: Billing route overlap message: >- Another active volume billing package already uses this transactionRoute for the same organization and ledger. Error0064: summary: Invalid free quota value: code: FEE-0064 title: Invalid free quota message: The freeQuota field must be a non-negative integer. Error0065: summary: Invalid discount tier value: code: FEE-0065 title: Invalid discount tier message: The discountPercentage must be between 0 and 100. Error0067: summary: Invalid count mode value: code: FEE-0067 title: Invalid count mode message: The countMode field must be `perRoute` or `perAccount`. Error0069: summary: Invalid account target value: code: FEE-0069 title: Invalid account target message: >- The accountTarget could not be resolved. Verify that segmentId, portfolioId, or the provided aliases exist in Midaz. Error0070: summary: Invalid fee amount value: code: FEE-0070 title: Invalid fee amount message: The feeAmount must be a positive value greater than zero. Error0004: summary: Internal Server Error value: code: FEE-0004 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````