How to Handle a High-Volume Chart of Accounts

Pleo caps a company at 11,000 active Accounts (Chart of Accounts entries). Some Accounting Systems maintain a full chart of accounts with tens of thousands of entries. Only a small fraction of these are ever relevant to Pleo, but syncing the full set can exceed the limit. This how-to explains how to handle that limit in your integration.

When to Use This

This how-to is useful when your integration is at risk of syncing more than 11,000 active Accounts to Pleo.

Prerequisites

Before you begin:

You’re familiar with Account Limits and High-Volume Sync Guidance.
Your integration is authenticated using one of the supported authentication methods.
Your integration can call Pleo’s Chart of Accounts API endpoints.

Steps

1. Filter to Expense-Relevant Accounts

Before fetching or matching anything, filter the AS chart of accounts to the accounts relevant for expense categorisation in Pleo. This is typically expense-type and P&L (profit and loss) accounts. Asset, liability, equity, and bank accounts are generally not needed, so exclude them. This step runs entirely on data already available from the AS. It does not call the Pleo API. Example Pseudo:

EXPENSE_RELEVANT_TYPES = {"EXPENSE", "PROFIT_AND_LOSS"}

all_as_accounts = fetchActiveAccountsFromAS()

filtered_as_accounts = []
for account in all_as_accounts:
    if account.type in EXPENSE_RELEVANT_TYPES:
        filtered_as_accounts.append(account)

The exact field used to classify accounts depends on what the AS exposes. If the AS does not expose an account type, fall back to the AS’s own chart of accounts numbering convention (for example, a defined range of account codes for expense accounts).

2. Check the Filtered Count Against the Limit

filtered_as_accounts, built in step 1, is what you want Pleo to have as active Accounts once the sync finishes. Check its size against the 11,000 limit before making any Pleo API calls. Example Pseudo:

filtered_count = len(filtered_as_accounts)

if filtered_count > 11000:
    log.error(
        f"Company {companyId}: filtered chart of accounts has "
        f"{filtered_count} accounts, exceeding Pleo's 11,000 "
        f"active Account limit by {filtered_count - 11000}. Sync aborted."
    )
    abortSync()
else:
    continueSync()  # proceed to step 3

You can do this check using only filtered_as_accounts, without looking at Pleo’s current Accounts at all, because Chart of Accounts Sync is a full reconciliation. By the end of a run, Pleo’s active Accounts always match filtered_as_accounts exactly:

An account in filtered_as_accounts that’s already active in Pleo: no change.
An account in filtered_as_accounts that’s missing, or archived, in Pleo: created or unarchived.
An account active in Pleo but not in filtered_as_accounts: archived.

For example: Pleo has 10,000 active Accounts today, and filtered_as_accounts has 9,500:

Outcome	Count
Already active in Pleo (no change needed)	8,500
Missing or archived in Pleo (create the missing ones, unarchive the rest)	1,000
Active in Pleo, but not in `filtered_as_accounts` (archive them)	1,500

Archive the 1,500 first, then create or unarchive the 1,000. After the sync, Pleo has 9,500 active Accounts (8,500 + 1,000), matching filtered_as_accounts exactly.

3. Archive Accounts No Longer in the Filtered Set First

Archive Accounts in this step. Account creation and unarchiving happen in the next step. Pleo never lets a company go over 11,000 active Accounts, and it checks the limit on both create and unarchive requests. If the company is close to the limit, a create or unarchive request sent before the archive step can be rejected with an HTTP 400, even though the sync would end up within the limit. Fetch Pleo’s current Chart of Accounts, including archived Accounts, the same way as How to Sync Accounts, then follow How to Create, Update, and Archive Accounts for the archive API request itself. The difference from that how-to is that you match against filtered_as_accounts, not all_as_accounts (the unfiltered list from step 1). Accounts excluded by filtering, for example asset or liability accounts, get archived here if they were previously synced as active. This step catches them on every sync run, so they don’t stay active in Pleo after they drop out of the filtered set. Example Pseudo:

pleo_accounts = fetchAccountsFromPleo(includeArchived: true)

filtered_external_ids = set()
for account in filtered_as_accounts:
    filtered_external_ids.add(account.externalId)

for account in pleo_accounts where archived == false:
    if account.externalId not in filtered_external_ids:
        account.archived = true
        PUT account to Pleo

4. Create or Unarchive the Remaining Accounts

Once the archive step has run, create the Accounts in filtered_as_accounts that are missing in Pleo, and unarchive the ones that were already archived in Pleo but that the sync now needs active.

If you have many Accounts to create, use the batch endpoint instead of individual requests: follow How to Create Multiple Accounts in a Single Request (max 1,000 Accounts per request).
Unarchive existing Accounts individually: follow How to Create, Update, and Archive Accounts.

5. Handle a Rejection from Pleo

If a sync skips the step 2 pre-check, Pleo doesn’t reject the whole sync at once. No single request can contain more than 1,000 Accounts (see How to Create Multiple Accounts in a Single Request). Instead, once the company’s active Accounts reach 11,000, further create calls (sent individually or as part of a batch) and further unarchive calls (always sent individually) get rejected outright with a top-level HTTP 400:

{"error": {"type": "BAD_REQUEST", "message": "Too many active accounts for company {companyId}"}}

A batch can still fail per-item for unrelated reasons, for example EXTERNAL_ID_ALREADY_EXISTS (see Handling Failures), even when it isn’t hitting the active Account limit. Check both error shapes in your response handling: a top-level 400 for exceeding the limit, and the per-item failed array for everything else. Example Pseudo:

for index, batch in enumerate(chunks(filtered_as_accounts, size=1000)):
    response = POST /v1/chart-of-accounts/batch with { companyId, items: batch }

    if response.status == 400:
        # Whole batch rejected, for example for exceeding the active Account limit
        log.error(f"Company {companyId}: batch {index}, containing {len(batch)} accounts, was rejected by Pleo: {response.body}")
        abortSync()
    else:
        # 201: the batch was accepted, but some items may have failed individually
        for failed_item in response.data.failed:
            log.error(f"Company {companyId}: account {failed_item.request.externalId} failed with reasons {failed_item.reasons}")

The same 400 can happen on a single unarchive call too, since unarchive is always sent individually via How to Create, Update, and Archive Accounts. Check response.status on that call the same way.

Error Codes

Scenario	HTTP Status	Notes
A create or unarchive request would exceed the company’s 11,000 active Account limit	`400`	`BAD_REQUEST`: “Too many active accounts for company `{companyId}`”. See 5. Handle a Rejection from Pleo above
One item’s `externalId` already exists in Pleo	`201`, item in `data.failed[]`	See How to Create Multiple Accounts in a Single Request: Error Codes
The batch request is structurally invalid, for example more than 1,000 items	`400`	See How to Create Multiple Accounts in a Single Request: Error Codes
Too many requests in a short period	`429`	See How to Create Multiple Accounts in a Single Request: Error Codes

Get Started

Integration Design

Workflow Guides

How-to's

How to Handle a High-Volume Chart of Accounts

When to Use This

Prerequisites

Steps

1. Filter to Expense-Relevant Accounts

2. Check the Filtered Count Against the Limit

3. Archive Accounts No Longer in the Filtered Set First

4. Create or Unarchive the Remaining Accounts

5. Handle a Rejection from Pleo

Error Codes

​When to Use This

​Prerequisites

​Steps

​1. Filter to Expense-Relevant Accounts

​2. Check the Filtered Count Against the Limit

​3. Archive Accounts No Longer in the Filtered Set First

​4. Create or Unarchive the Remaining Accounts

​5. Handle a Rejection from Pleo

​Error Codes

​Related Reading

When to Use This

Prerequisites

Steps

1. Filter to Expense-Relevant Accounts

2. Check the Filtered Count Against the Limit

3. Archive Accounts No Longer in the Filtered Set First

4. Create or Unarchive the Remaining Accounts

5. Handle a Rejection from Pleo

Error Codes

Related Reading