A charge code is a reusable billing template that defines what is billed, how much, and how it is reported to your SIS. Every transaction in the system references one. Charge codes are managed at Admin › Setup › Billing under the Primary Charges tab and are then assigned to bed types, meal plans, or workflow triggers within a housing cycle.
Coattail charge codes are a special type of secondary charge that posts automatically alongside a primary charge. They are useful for mandatory fees tied to a specific billing event, such as an administrative processing fee applied to every housing charge.
What a charge code stores
Each charge code carries a set of fields that control how the system generates transactions and how those transactions interact with your SIS and the student balance.
Labels and identifiers
Name — the internal system label
Custom Name — the human-friendly label shown in the admin interface; must be unique per tenant
Default accounting code — the accounting code that tells your financial system where to record revenue
Refund accounting code — the accounting code used when the charge is refunded
External ID — the link to the corresponding record in your SIS
Description — an optional description
Amount and behavior
Default amount — the default amount posted for transactions created from this code
Refundable — whether the charge can be reversed; if false, a refund attempt returns SKIPPED_NON_REFUNDABLE
isTaxable — whether tax rules apply
isRecurring — whether the charge repeats on a schedule
Include in balance — whether transactions from this code count toward the student's User Balance
Applicability
Tags — an integer array that controls which students a code applies to automatically based on their profile tags
Type
CHARGE — a standard charge code
COATTAIL — a secondary charge that rides alongside a primary charge
Admin surface
Charge codes are managed at Admin › Setup › Billing. The page shows two tabs:
Primary Charges — the main charge codes used for housing, meal plans, and fees
Coattail Charges — secondary charges that attach to a primary charge code
The charge-code collection at /api/v2/charge-codes returns only primary charge codes (type CHARGE). Coattail charges are managed through a separate service and UI.
Row actions on the charge-code table include Edit Details, Activate, Deactivate, and Mark as No Transfer. Status is shown as Active or Inactive.
When a charge code is marked non-refundable, the UI shows a tooltip: "This Charge Code is Non-Refundable. Refunds will not be issued for transactions using this code."
Coattail charge codes
A coattail charge is a secondary charge automatically applied alongside a primary one. A coattail charge code is a Cost with type = COATTAIL and a parentCostId pointing at the primary charge code.
Coattail charges can only be added to a primary charge code. If you try to attach a coattail to anything other than a primary CHARGE, the system throws: "Coattail charges can only be added to primary charge codes."
The amount can be either a fixed dollar amount or a percentage of the primary charge. The two rate fields are mutually exclusive:
Fixed Amount ($) — a flat dollar amount
Percentage (%) — a percentage of the primary charge amount
In transaction logic, a fixed amount takes precedence if present; otherwise the amount is derived from the parent amount using the percentage. Zero-amount coattails are skipped and do not create transactions.
When the primary charge is posted, the system resolves each active coattail and posts it as its own transaction. The coattail card subtitle in the admin UI states: "Any time the primary charge is created, individual transactions will be created for every active Coattail Charge."
Example: an "Administrative Processing Fee" set as a 5% coattail on a room charge posts automatically every time that room charge is created, as a separate line on the student ledger.
Coattail form validation
Creating or editing a coattail charge requires:
Name — required
Default Accounting Code — required
Rate Type — either Fixed Amount or Percentage
Rate Amount — must be greater than zero
Optional fields include Refund Accounting Code and Is Refundable.
On update, only coattail charges can be changed through the coattail edit path. Editing a non-coattail charge through this method produces: "Only coattail charges can be updated through this method."
How charge codes fit into the billing workflow
Charge codes are created at the system level, then referenced within a cycle. The Finance tab in a cycle editor assigns charge codes to bed types and meal plans so that assignments generate automated costs. The Fees tab assigns charge codes to one-time events such as application submissions or approvals.
All charge codes must match your SIS billing codes exactly. Mismatches cause export failures and require manual reconciliation.
Permissions
Creating, updating, and managing charge codes requires the manageBillingCodes permission.
Related articles
How Transactions Flow explains the lifecycle events and lineage model for transactions created from charge codes.
Refund vs. Credit vs. Ad-hoc Transaction explains the difference between the three ways money can be moved on a student ledger.