Charge service fees to an account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCodes": [
    "PAPER_STATEMENT",
    "CARD_REISSUE"
  ],
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

	payload := strings.NewReader("{\n  \"serviceCodes\": [\n    \"PAPER_STATEMENT\",\n    \"CARD_REISSUE\"\n  ],\n  \"description\": \"Tarifas de serviço de outubro\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serviceCodes: ['PAPER_STATEMENT', 'CARD_REISSUE'],
    description: 'Tarifas de serviço de outubro',
    metadata: {}
  })
};

fetch('https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

payload = {
    "serviceCodes": ["PAPER_STATEMENT", "CARD_REISSUE"],
    "description": "Tarifas de serviço de outubro",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "accountPlanId": "00000000-0000-0000-0000-000000000000",
  "accountPlanVersion": 1,
  "assetCode": "BRL",
  "createdAt": "2026-10-22T12:00:00Z",
  "feeTransactionIds": [
    "<string>"
  ],
  "id": "00000000-0000-0000-0000-000000000000",
  "items": [
    {
      "amount": "3",
      "feeKey": "extratoImpresso",
      "freeQuota": 2,
      "outcome": "charged",
      "serviceCode": "PAPER_STATEMENT",
      "unit": 3
    }
  ],
  "ledgerId": "00000000-0000-0000-0000-000000000000",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "period": "2026-10",
  "totalAmount": "15",
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Charge service fees to an account

Charges service fees of the account plan of the account. Each occurrence of a code in serviceCodes is one unit. Units inside the free quota of their fee come out as quota and cost nothing; units past it come out as charged at the fee’s flat amount. Codes the account’s plan does not declare, and every code of an account without a plan, come out as not_covered and consume nothing. All charged units post in a single fee transaction in the account’s asset, debiting the account and crediting each fee’s creditAccount, on the fees’ transaction route when the ledger validates accounting routes; neither account plans nor fee packages apply to it. When no unit is charged the charge is recorded without a transaction. The X-Idempotency header is required (400, 0552); a retry with the same key and body returns the recorded charge with X-Idempotency-Replayed and charges nothing again. A code no fee of the ledger declares is refused (422, 0549), as is a code only transaction fees declare (422, 0550) and codes whose fees have different transaction routes (422, 0551). When the fee transaction is refused, for insufficient funds for instance, the charge is refused with the same error and nothing is consumed. ledgerId in the query or the body is refused with 0235.

POST

organizations

{organization_id}

ledgers

{ledger_id}

accounts

{account_id}

fee-charges

Charge service fees to an account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCodes": [
    "PAPER_STATEMENT",
    "CARD_REISSUE"
  ],
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

	payload := strings.NewReader("{\n  \"serviceCodes\": [\n    \"PAPER_STATEMENT\",\n    \"CARD_REISSUE\"\n  ],\n  \"description\": \"Tarifas de serviço de outubro\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serviceCodes: ['PAPER_STATEMENT', 'CARD_REISSUE'],
    description: 'Tarifas de serviço de outubro',
    metadata: {}
  })
};

fetch('https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

payload = {
    "serviceCodes": ["PAPER_STATEMENT", "CARD_REISSUE"],
    "description": "Tarifas de serviço de outubro",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "accountPlanId": "00000000-0000-0000-0000-000000000000",
  "accountPlanVersion": 1,
  "assetCode": "BRL",
  "createdAt": "2026-10-22T12:00:00Z",
  "feeTransactionIds": [
    "<string>"
  ],
  "id": "00000000-0000-0000-0000-000000000000",
  "items": [
    {
      "amount": "3",
      "feeKey": "extratoImpresso",
      "freeQuota": 2,
      "outcome": "charged",
      "serviceCode": "PAPER_STATEMENT",
      "unit": 3
    }
  ],
  "ledgerId": "00000000-0000-0000-0000-000000000000",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "period": "2026-10",
  "totalAmount": "15",
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

Required. Idempotency key of the charge, unique per account: a retry with the same key and body returns the recorded charge with X-Idempotency-Replayed, a different body under the same key answers 409 (0084).

Path Parameters

organization_id

string

required

Organization ID (UUID)

ledger_id

string

required

Ledger ID (UUID)

account_id

string

required

Account ID (UUID)

Body

application/json

serviceCodes

string[] | null

required

Service codes to charge, 1 to 100. Each occurrence is one unit; codes are normalized to trimmed upper case.

Required array length: 1 - 100 elements

Example:

["PAPER_STATEMENT", "CARD_REISSUE"]

description

string

Description of the charge, also used as the description of the fee transaction.

Maximum string length: 256

Example:

"Tarifas de serviço de outubro"

metadata

object

Flat metadata of the charge, also written to the fee transaction.

Show child attributes

Response

Created

accountId

string

required

Example:

"00000000-0000-0000-0000-000000000000"

accountPlanId

string

required

Account plan active for the account when the charge was taken; null when the account had none.

Example:

"00000000-0000-0000-0000-000000000000"

accountPlanVersion

integer<int64>

required

Version of the account plan in effect when the charge was taken; 0 when the account had no plan.

Example:

1

assetCode

string

required

Asset of the account the charge was taken in.

Example:

"BRL"

createdAt

string<date-time>

required

Example:

"2026-10-22T12:00:00Z"

feeTransactionIds

string[] | null

required

Fee transactions that charged the charged items; empty when nothing was charged.

string

required

Example:

"00000000-0000-0000-0000-000000000000"

items

object[] | null

required

One item per service code of the request, in request order.

Show child attributes

ledgerId

string

required

Example:

"00000000-0000-0000-0000-000000000000"

organizationId

string

required

Example:

"00000000-0000-0000-0000-000000000000"

period

string

required

Monthly quota period (YYYY-MM) the units were counted in, in the plan timezone.

Example:

"2026-10"

totalAmount

string

required

Sum of the amounts of the charged items.

Example:

"15"

description

string

Example:

"Tarifas de serviço de outubro"

metadata

object

Show child attributes

Getting started

Core

CRM

Fees

Error handling

Events

Charge service fees to an account

Authorizations

Headers

Path Parameters

Body

Response