SLAs & async behavior

Taxbit calculates inventory and gains automatically every time it processes a transaction, but the calculation runs in the background. POST /v1/transactions/external-id returns as soon as the transaction is ingested, before inventory reflects it. So there is always a short window in which a read of inventory or gains shows the account as it was before the transaction you sent.

How long the lag is

How long that window lasts depends on where the transaction lands in the account's history.

• The newest transaction for an account is usually reflected in under a second when transactions arrive in order.
• A transaction that lands earlier in an account's history is a historical change and has no SLA (service-level agreement).

The first figure is an unofficial P95 (95th percentile) for end-to-end inventory calculation on append transactions: transactions that are the latest for their account. A historical change has no SLA because it can require recalculating the account's entire inventory from that point forward.

This is why Set up inventory and gains asks you to send transactions in order, as soon as your platform processes them. Sent that way, each transaction is the newest for its account when it arrives.

Changes that recalculate history

Some changes always act on history, however promptly you send them:

• Backfilling older transactions, or correcting an older one by resending its id.
• Adding a backdated entry to an account's cost-basis method (disposition_method) history. Gains from the entry's effective date forward recalculate within about three seconds; see Choose a disposition method.

After any of these, figures you read or showed earlier can change. Don't cache inventory or gains across a backfill or a method change.

Knowing when figures are current

Two signals exist, and neither is a guarantee on its own.

• The INVENTORY_UPDATE webhook is the better one. Taxbit sends it when an account's inventory changes, with the start of the affected range, so you know what to read again. It is not guaranteed after every write.
• calculation_status appears on inventory and gains responses as in_progress or complete. complete means no calculation is currently tracked for the account. It does not mean the latest write is reflected: a cost-basis method history entry, for example, does not mark the account as calculating, so a read right after one can show complete with the old figures.

So treat complete as "nothing is known to be running", not as confirmation that a particular change has landed. To confirm a specific change, check that the figures reflect it. Real-time inventory shows the webhook and polling patterns.

Where to go next

• Real-time inventory: refresh on the webhook, or poll the summary's latest transaction.
• Set up inventory and gains: the end-to-end walkthrough.