Chart of Accounts

Keep account names, source identity, reporting details, and supplier cost-account choices aligned with connected finance workflows.

Endpoints

Endpoint	Scope	Use it for
`GET /reference/ledger-accounts`	`company-reference:read`	Find accounts by name, source ID, or account type.
`GET /reference/ledger-accounts/{id}`	`company-reference:read` or `company-reference:write`	Read one selected account and its current update time.
`POST /reference/ledger-accounts`	`company-reference:write`	Preview or create one account.
`PATCH /reference/ledger-accounts/{id}`	`company-reference:write`	Preview or update one account.

GET /me reports directory access under effectiveCapabilities.companyReference.ledgerAccounts. Create and update access appear under effectiveCapabilities.companyReference.write.ledgerAccountsCreate and ledgerAccountsUpdate.

Find and read accounts

Filter the directory by matching text in q, an exact source externalId, or one of five account types:

ASSET
LIABILITY
EQUITY
REVENUE
EXPENSE

curl "$SHELFCYCLE_API_BASE_URL/reference/ledger-accounts?accountType=EXPENSE&q=freight" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Supplier account setup"

Rows include the account ID, name, source ID, account type, report-exclusion setting, income-statement flags, and updatedAt. When meta.nextCursor is available, continue with the returned cursor.

Read one selected account before updating it:

curl "$SHELFCYCLE_API_BASE_URL/reference/ledger-accounts/ledger-account-id" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

The detail response also includes categoryId, which can be preserved or updated with the account.

Preview and create an account

Every create requires name and accountType. You can also provide a stable source ID, reporting category, report-exclusion setting, and an income-statement classification.

curl "$SHELFCYCLE_API_BASE_URL/reference/ledger-accounts?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Freight Expense",
    "accountType": "EXPENSE",
    "externalId": "GL-FREIGHT-6100",
    "excludeFromReports": false,
    "incomeStatementType": "isOrdinary"
  }'

Review the readiness response, then send the identical request without dryRun=true. When externalId is absent, use a stable Idempotency-Key for the create request. When a source ID is present, repeating the same source identity or exact name returns the existing account when it matches.

Income-statement classification accepts:

Value	Use it for
`isCogs`	An expense account included in cost of goods sold.
`isOrdinary`	An ordinary revenue or expense account.
`isNonOrdinary`	A non-operating revenue or expense account.

Update an account

Use the selected account's latest updatedAt value in If-Match. You can update its name, source ID, category, report-exclusion setting, account type, or income-statement classification.

curl "$SHELFCYCLE_API_BASE_URL/reference/ledger-accounts/ledger-account-id?dryRun=true" \
  -X PATCH \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2026-09-16T21:36:40.961Z" \
  -d '{
    "name": "Outbound Freight Expense",
    "externalId": "GL-FREIGHT-6100"
  }'

After review, send the same PATCH without dryRun=true. The response returns the saved account, its new updatedAt, and whether anything changed. If the account changed after your read, fetch it again and rebuild the update from its current state.

Names, source IDs, categories, and report inclusion can stay current as the chart evolves. Account type and income-statement classification can change while the account has no financial activity or connected assignments; once it is established in those workflows, ShelfCycle preserves its accounting meaning.

Continue into supplier setup

Save the returned ledger-account ID when the account will be used as a supplier's default cost account, then send it as costLedgerAccountId in the supplier create or update request. See Account setup for the complete connected workflow.

Guardrail

Read the current account before changing it, preserve the exact account type and reporting meaning from the source system, and use the latest updatedAt value for every update.