Skip to main content

​
Payroll → Books GL posting

When a payroll run completes, Fluide Payroll publishes a PAYROLL_RUN_COMPLETED event. Fluide Books consumes it and posts a double-entry journal entry using subsidiary-scoped payroll account mappings.

​
Prerequisites

  • Books subsidiary configured for the company
  • Payroll runs completing successfully — Run payroll
  • Payroll GL mappings configured per subsidiary

​
Required mapping codes

Each subsidiary needs mappings for at minimum:
componentCodeDebitCredit
SALARY_EXPENSERequired—
EMPLOYER_CONTRIBUTION_EXPENSERequired—
NET_SALARY_PAYABLE—Required
PAYROLL_CASH—Required
Configure mappings via Books HTTP APIs (audited) — see Payroll account mappings in Books API reference.

​
Steps

1

Configure payroll GL mappings

# Example — see API reference for full schema
curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/books/payroll-account-mappings" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "Content-Type: application/json" \
  -d '{
    "subsidiaryId": "YOUR_SUBSIDIARY_ID",
    "componentCode": "SALARY_EXPENSE",
    "debitAccountId": "ACCOUNT_UUID"
  }'
Repeat for each required componentCode.
2

Complete a payroll run

Process and complete a run — Run payroll. GL posting triggers on completion, not on draft or calculate.
3

Verify journal entry in Books

List journal entries for the period and confirm a posted payroll entry exists:
curl -sS "$FLUIDE_BASE_URL/api/v1/books/journal-entries?from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer"

​
Tips

  • Mappings are per subsidiary — multi-entity companies need a complete set for each legal entity.
  • Posting is event-driven and idempotent on replay — re-consuming the same run event does not duplicate entries.
  • Partner integrations: include acting-client headers on Books API calls when scoping to a merchant.

​
Troubleshooting

ProblemResolution
Run completed, no journalMissing or incomplete payroll_account_mappings for the subsidiary.
Unbalanced entryVerify debit/credit account IDs exist in the subsidiary COA.
Wrong amountsCheck run totals and mapping componentCode coverage.

Run payroll

Complete a run to trigger posting.

Books API reference

Mappings and journal entry endpoints.