Skip to main content
POST
/
v1
/
billing-packages
curl --request POST \
  --url https://fees.sandbox.lerian.net/v1/billing-packages \
  --header 'Content-Type: <content-type>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "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"
}
'
{
  "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"
}

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.

Headers

​
X-Organization-Id
string
required

The unique identifier of the Organization associated with the request.

Example:

"019c96a0-0a98-7287-9a31-786e0809c769"

​
Authorization
string

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 documentation.

​
Content-Type
string
required

The type of media of the resource. Must be application/json.

Example:

"application/json"

Body

application/json

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
enum<string>
required

Billing type: volume or maintenance.

Available options:
volume,
maintenance
Allowed value: "volume"
​
label
string
required

Name of the billing package.

​
ledgerId
string
required

Ledger that records the billing transactions.

​
eventFilter
object
required

(Volume only) Filter for which transactions to count.

​
pricingModel
enum<string>
required

(Volume only) Pricing model.

Available options:
tiered,
fixed
​
tiers
object[]
required

(Volume only) Quantity ranges and unit prices. At least one tier is required.

Minimum array length: 1
​
assetCode
string
required

Currency code (e.g., BRL).

​
debitAccountAlias
string
required

(Volume only) Account to debit.

​
creditAccountAlias
string
required

(Volume only) Account to credit.

​
description
string

Optional description.

​
enable
boolean

Whether the package is active. Optional. Defaults to true when omitted.

​
freeQuota
integer

(Volume only) Transactions exempt before charging.

​
discountTiers
object[]

(Volume only) Progressive discount thresholds.

​
countMode
enum<string>

(Volume only) How transactions are grouped.

Available options:
perRoute,
perAccount
​
feeAmount
string

(Maintenance only) Fixed fee per active account. Decimal value as a string (e.g., "9.90").

​
maintenanceCreditAccount
string

(Maintenance only) Account that receives the fee.

​
accountTarget
object

(Maintenance only) Target accounts. Provide exactly one of segmentId, portfolioId, or aliases.

Response

Billing package created successfully.

​
id
string

Unique identifier of the billing package.

​
label
string
​
description
string
​
type
enum<string>
Available options:
volume,
maintenance
​
enable
boolean
​
organizationId
string
​
ledgerId
string
​
eventFilter
object
​
pricingModel
string
​
tiers
object[]
​
freeQuota
integer
​
discountTiers
object[]
​
countMode
string
​
assetCode
string
​
debitAccountAlias
string
​
creditAccountAlias
string
​
feeAmount
string
​
maintenanceCreditAccount
string
​
accountTarget
object
​
createdAt
string<date-time>
​
updatedAt
string<date-time>
​
deletedAt
string<date-time> | null