# Chart of Accounts

Find, create, and maintain accounts used by connected finance and supplier workflows.

Canonical HTML: https://developer.shelfcycle.com/guides/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:

```text
ASSET
LIABILITY
EQUITY
REVENUE
EXPENSE
```

```bash
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:

```bash
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.

```bash
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.

```bash
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](/guides/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.