{"openapi":"3.1.0","info":{"title":"Integration Runtime API","version":"1.0.0-emitted","description":"Multi-product SaaS integration runtime — product backend API.\n\nProduct backends authenticate to the runtime with HMAC-signed requests; the signing\ncontract and test vectors are in the getting-started guide published with this file.\nEvery operation in this document is intended for **product backends**, called from a\ntrusted server, never from a browser.\n\n**Source of truth.** This file is generated from the runtime's own request and response\nschemas. Do not edit it by hand.\n\n## Errors\n\nEvery error the runtime itself produces is RFC 7807 `application/problem+json`.\n`code` is the machine-readable discriminator — **switch on `code`, never on `title` or\n`detail`**, which are human-facing and may be reworded in any release. `request_id` is on\nevery problem body; quote it when you escalate.\n\n`code` is an open string, not an enum: new codes ship in MINOR releases and a client must\nnot reject one it has not seen. Fall back on the status class — `4xx` means do not retry\nunless it is a `429`; `5xx` means retry with jittered backoff.\n\n**Request-schema validation failures** are `400 request.validation_failed`, in the same\nenvelope as everything else. They additionally carry an `errors` array: one entry per\noffending field, whose `field` is prefixed with where the value was read from — `body.`,\n`query.`, `path.`, `header.` or `cookie.` — so the same name in two targets stays\ndistinguishable. `errors[].code` is a validator diagnostic label, useful in a log and NOT a\nstable branch point; branch on the top-level `code`. The array is capped at 20 entries and\neach `message` is truncated, so a corrected request may surface further failures.\n\nThe table below is the catalogue for this, the product-backend API. The same machine-readable\nlist is emitted as the `x-ir-error-codes` extension on `info`.\n\n| Code | Status | Cause | What to do | Retry |\n|---|---|---|---|---|\n| `accounting.invalid_input` | 400 | A neutral accounting request has an unknown or duplicate query parameter, a tax_code mapping or bind row without `treatment`, or `treatment` on any other kind. For a QuickBooks payment or refund it can also mean a ref was left out (payment: payment_method and/or deposit_account; refund: payment_method only) before omitting it is enabled for the app; the job fails on its first attempt, its error message names the field, and nothing was sent. | Fix the request; send only documented neutral fields. When `errors` is present, each entry names the offending field (bind rows as `body.bindings[i].treatment`). For an omitted payment or refund ref, send the named field under a new idempotency key; the job can still be refused for another expanded case (for example a refund with mixed funding, decided after QuickBooks reads). | not without a change |\n| `accounting.connection_not_found` | 404 | The connection id does not exist for this tenant, or it is not an accounting connection. | Read the tenant's accounting connection from GET /v1/accounting/providers. | not without a change |\n| `accounting.no_accounting_connection` | 409 | The tenant has no active accounting connection, or the named one is not connected. | Have the tenant connect an accounting provider, then retry. | not without a change |\n| `accounting.connection_exists` | 409 | POST /v1/connections/connect-session for an accounting provider while the customer already has an active connection to a different accounting provider. `connection_id` and `provider_key` name it. | Disconnect the existing accounting connection first (POST /v1/connections/{id}/disconnect), then start the new connection. Documents stay in the old provider. | not without a change |\n| `accounting.multiple_accounting_connections` | 409 | The tenant has more than one active accounting connection; neutral calls need exactly one. | Disconnect the connection the tenant no longer uses. | not without a change |\n| `accounting.provider_unavailable` | 503 | The accounting provider is not enabled for the app, or a provider read through the connection coordinator was not confirmed. A refused bind may carry `reason`: pending_change (a create or update of the ERP record, or another change of its mapping, is in progress) or connection_changed (the connection was reconnected during the bind). | Retry later with a fresh signature; escalate if it persists. | once, then escalate |\n| `accounting.snapshot_unsupported` | 422 | A record snapshot was requested for a provider that does not support snapshots yet (QuickBooks and Xero today). | Use the paged records list and match routes for this connection. | not without a change |\n| `accounting.snapshot_refresh_too_soon` | 409 | A new snapshot (a `refresh`, or a restart after a failed one) was requested less than 15 minutes after the last one on the same connection. `snapshot_id` names that snapshot. | Use the named snapshot, or retry after `Retry-After`. | safe to replay |\n| `accounting.snapshot_capacity` | 503 | Snapshot storage for the app database is at its row ceiling. | Retry after `Retry-After`, or match without a snapshot. | safe to replay |\n| `accounting.snapshot_not_enabled` | 403 | Record snapshots are not enabled for this app or tenant yet. | Use the paged records list and match routes; ask the runtime operator to enable snapshots. | not without a change |\n| `accounting.snapshot_refused` | 400 | The snapshot's background job was not admitted. The status is the admission's own; `provider_detail` names the underlying refusal. | Read `provider_detail`; retry only if `Retry-After` is present. | once, then escalate |\n| `accounting.snapshot_conflict` | 409 | Another snapshot request for the same connection and record type won a race. | Retry the request; it returns the running snapshot. | safe to replay |\n| `accounting.snapshot_not_found` | 404 | No snapshot has been taken for this connection and record type, or (for `source: snapshot` or a `q` search) none is ready and usable. | Start one with POST .../snapshots, or match and list with `source: live`. | not without a change |\n| `accounting.snapshot_not_ready` | 409 | A records match or list asked for a snapshot (or `auto`) while a snapshot pull for this connection and record type is still running, and no ready one is usable. `snapshot_id` names the pull. | Wait for the snapshot job's `sync_job.completed` webhook, or retry after `Retry-After`; or use `source: live`. | safe to replay |\n| `accounting.bind_job_unsupported` | 422 | A bind job was requested for a record type other than customer or item, or for a provider without bind jobs (QuickBooks and Xero today). | Bind other record types with POST .../records/{entity}/bind, 25 rows per call. | not without a change |\n| `accounting.bind_job_too_large` | 413 | A bind job was sent more than 5,000 rows. | Split the bindings into jobs of at most 5,000 rows, one after another. | not without a change |\n| `accounting.bind_job_in_progress` | 409 | A bind job is already pending or running for this connection. `job_id` names it when known. | Wait for that job's `sync_job.completed` or `sync_job.dead_lettered` webhook, then start the next one. | safe to replay |\n| `accounting.bind_job_not_enabled` | 403 | Bind jobs are not enabled for this app or tenant yet. | Use POST .../records/{entity}/bind; ask the runtime operator to enable bind jobs. | not without a change |\n| `accounting.bind_job_refused` | 400 | The bind job's background job was not admitted. The status is the admission's own; `provider_detail` names the underlying refusal. | Read `provider_detail`; retry only if `Retry-After` is present. | once, then escalate |\n| `accounting.bind_job_not_found` | 404 | No bind job with this job id exists for this connection and record type, or its results passed the 7-day retention. | Check the job id from the start response or the webhook. | not without a change |\n| `accounting.match_too_many` | 422 | A live records match was sent more than 100 records (`max_records`); 1,000 are allowed only against a ready snapshot. | Send at most 100 records per live call, or take a snapshot first. | not without a change |\n| `accounting.rate_limited` | 429 | The connection's provider quota is exhausted for this read. | Wait for Retry-After, then re-sign and retry. | re-sign first |\n| `accounting.reference_not_found` | 404 | No provider record matches the provider reference or exact name. | Pick a reference from the provider's current records. | not without a change |\n| `accounting.reference_invalid` | 409 | The provider record exists but cannot be used for this kind (wrong account type, inactive, ambiguous or unsupported). | Choose an active record of the right type. `reason` says which: inactive or not_usable_for_kind. | not without a change |\n| `accounting.mapping_not_found` | 404 | No mapping exists for this ERP code on the tenant's accounting connection. | Create the mapping with PUT before using the code. | not without a change |\n| `accounting.mapping_conflict` | 409 | The provider record is already bound to another ERP id, or the record is ambiguous or unsupported, or changed during verification. Binding an ERP id that is already bound to a different provider record re-binds it on every provider. | Read `reason`: bound_to_other_record (`bound_erp_id` holds the record: unmap or rebind that ERP id, or choose another record), record_already_bound (no longer returned by a bind; keep `bound_provider_ref` or bind the ERP id to it), not_usable_for_kind or ambiguous (choose another record). `reason` is absent only when the runtime cannot tell. | not without a change |\n| `accounting.unsupported_change` | 409 | The requested change is not supported, e.g. deleting a company-bound customer or item mapping, or a QuickBooks item update whose `type` differs from the provider item (refused at submit, or as the job's error if the item changed in between). Also the job's error for a payment void, delete or update that the runtime or the provider does not allow: a payment over several invoices, a credit application, a payment named by a refund written through this API, a QuickBooks delete of a voided payment, a QuickBooks payment in a bank deposit (fault 6540), a QuickBooks payment update whose amount QuickBooks still refuses against the payment's charges (fault 6000; a lowered amount normally lowers the invoice application with it), or a Xero payment that is reconciled or part of a batch payment; and for a QuickBooks invoice void or delete after the other one succeeded. Nothing was written. | Rebind the record to the correct provider reference instead. For a payment reversal, fix the cause in the provider first (remove the payment from its QuickBooks deposit, or unreconcile it or remove it from its Xero batch), then send a new void_id, delete_id or change_id with a new idempotency key. For a refused payment update amount, refresh the payment and review it with a person first. A payment named by a runtime refund cannot be reversed, and a voided QuickBooks payment is not deleted. A repeat of the same reversal of an already voided or deleted payment is not refused: it completes with no write. | not without a change |\n| `accounting.mapping_missing` | 409 | A neutral write names an ERP customer, item or code with no usable mapping for the connection. `mapping_kind`, `mapping_erp_code` and `mapping_state` say what to map; `mapping_state` `inactive` or `drifted` means the mapped provider record was archived, deleted or is no longer usable for the kind. | Map the named record or code (PUT .../mappings/{kind}/{erp_code}), then resend the same request. | not without a change |\n| `accounting.tax_mismatch` | 409 | The ERP's expected tax does not match the mapped tax codes: a tax_lines component is not in the code, or the tax lines do not add up to total_tax. Also returned when the provider's verification refuses the tax. | Recompute tax from the mapped codes, or send per-rate tax_lines; use a new idempotency_key for the corrected request. | not without a change |\n| `accounting.idempotency_conflict` | 409 | The idempotency_key was already used on this connection for a different neutral request, or the connection now points at a different provider company than when the key was first used. | Resend the original request unchanged, or use a new idempotency_key for a new request. | not without a change |\n| `accounting.capability_unsupported` | 422 | The connected provider does not support this operation or currency yet (QuickBooks: CAD home currency only), or the request needs a QuickBooks expanded case (for example a payment across several invoices, a refund with mixed funding, or an expanded invoice update) that is not qualified for the app (nothing was written). Xero answers it for accounting.payment.update (Xero has no payment update: delete the payment, then create a new one under a new erp_id) and accounting.invoice.delete (Xero deletes draft invoices only: void instead). | Read GET /v1/accounting/providers capabilities before offering the action. Do not retry an expanded-case refusal; it succeeds only after the case is qualified for the app. | not without a change |\n| `accounting.operation_in_progress` | 409 | A customer or item write for this ERP id, another update, void or delete of the same invoice, or another void, delete or update of the same payment (for a refund: of the payment it returns), or another apply or unapply of the same prepayment, is still pending at the provider or awaiting operator reconciliation. | Poll the earlier operation to completion, then resend. | once, then escalate |\n| `accounting.revision_conflict` | 409 | The provider document no longer matches the ERP's expected_revision or before-state (for a master record: the runtime has no current revision for it). Nothing was changed. | Refresh the record (for a master record, PUT the same mapping again), review the provider's current state, then resend with a new idempotency key. | not without a change |\n| `accounting.invoice_has_payment` | 409 | A Xero void of an invoice that has a payment (or a credit) applied. Xero voids only invoices with nothing applied, so nothing was sent. QuickBooks voids and deletes such an invoice and leaves the payment unapplied, so it does not return this code. On an async job it is the job's `error.code`; a provider that checks at admission returns it synchronously. | Remove or unapply the payment in the provider first, then resend the void with a new idempotency key; or credit the invoice (accounting.credit_memo.create) instead. | not without a change |\n| `accounting.amount_exceeded` | 409 | The provider refused the amount: a refund over what was paid on the invoice, or a returned or credited line over what remains of the original line. A prepayment apply over the invoice's open balance or the prepayment's remaining credit answers it too; on QuickBooks the runtime refuses it before anything is sent. | Refresh the invoice (or the prepayment) and reduce the amount. | not without a change |\n| `accounting.document_unlinked` | 409 | The ERP document (an invoice, or the payment a refund returns) has no verified provider document on this connection, or the invoice has two different ones. With `reason` mapping_changed: the ERP prepayment of an accounting.prepayment.apply was re-bound to another credit after the request was accepted; its job is cancelled (or, on a whole-job replay of its failed job, no replay job is created). Nothing was sent. | Create the invoice through the runtime first, or link one it created through quickbooks(), then resend. For mapping_changed, resend the apply under a new idempotency_key: it uses the credit the ERP prepayment holds now. | not without a change |\n| `accounting.link_conflict` | 409 | The invoice is already linked with a different line map, or its provider invoice is linked to another ERP id. Nothing was changed. | Send the line map that is already recorded, or contact support (the address is in your Console footer) to correct it. | not without a change |\n| `accounting.operation_disabled` | 403 | The native operation this request translates to is disabled, killed or not permitted for the app or tenant, or the request carries an optional field (`invoice.reference`) whose provider capability is disabled. `provider_detail` carries the native code. | Do not retry; the operation must be enabled by the operator. | not without a change |\n| `accounting.reconnect_required` | 409 | The connection's grant lacks a scope this operation needs: it was consented before the operation needed it (Xero: accounting.prepayment.create needs accounting.banktransactions). `missing_scopes` lists them, space-separated; `provider_detail` carries the native code. Refused before any job exists; nothing was sent. | Ask the customer to reconnect the connection (the same connect-session flow as Reconnect), then resend the same request unchanged. GET /v1/accounting/connections/{id}/capabilities shows the operation with reason reconnect_required until then. | not without a change |\n| `accounting.provider_refused` | 400 | Native admission refused the translated request for a reason without a neutral equivalent. `provider_detail` carries the native code; the HTTP status is the native status. | Read provider_detail; fix the request or escalate. | not without a change |\n| `accounting.operation_not_found` | 404 | No neutral accounting operation with this job id exists for the tenant. | Use the job_id returned by POST /v1/accounting/operations. | not without a change |\n| `accounting.record_type_disabled` | 409 | Syncing this record type is turned off in the connection's accounting settings. `record_type` names it. | Turn the record type on with PUT /v1/accounting/connections/{id}/settings if it should sync, then resend. | not without a change |\n| `accounting.before_sync_start` | 409 | A new document was created before the connection's sync_start_date (by default the day the provider was connected), judged by erp_created_at when the request sends it and by the document date otherwise. Writes to a document already linked on the connection (update, void, delete, payment changes) are never refused by the sync start. | If the document was created on or after the sync start date but dated earlier, resend it with erp_created_at (the same idempotency key is accepted). Otherwise keep it in the ERP only, or move sync_start_date earlier with PUT /v1/accounting/connections/{id}/settings after matching or linking the provider's existing records of that period, then resend. | not without a change |\n| `accounting.document_exists` | 409 | The provider already has a document with this number (voided ones count), or a customer with this name or an item with this code (archived ones count), or a Xero refund resumed after an operator reconciled it by linking a cash refund made by hand, or a create that names the erp_id of an invoice or payment that was deleted (an erp_id is never reused after a delete; create it under a new erp_id). On QuickBooks a customer's name must also be unused by any vendor or employee, compared without regard to letter case; the title names the record type and id that uses it. Nothing was created. `candidate_provider_id` names the existing document when known (for a name, only a customer or item the ERP could bind). It may come back synchronously from POST /v1/accounting/operations or as the job's error. | Renumber the document in the ERP and send it with a new idempotency key. For a name, rename the record in the ERP, or bind the existing customer or item (PUT .../mappings) instead of creating. Only when the existing invoice was created by the runtime through quickbooks() on this connection can PUT .../documents/invoice/{erp_id}/link adopt it instead; an invoice entered directly in the provider cannot be linked. For a reconciled Xero refund, `candidate_provider_id` names the cash refund the operator linked: the refund is complete, so record it and do not resend. | not without a change |\n| `accounting.write_uncertain` | 409 | A provider write may have reached the provider but was not confirmed, or the provider holds a document that differs from what was sent. The runtime never re-sends it; the ERP record stays fenced until an operator reconciles it. | Do not resend. Check the record in the provider and ask the runtime operator to reconcile the command. | not without a change |\n| `accounting.refund_incomplete` | 409 | A Xero refund is written in two steps: a credit note against the invoice, then a cash refund of that credit note. The credit note was written and verified; the cash refund was proved not written (it was refused, or refused before it was sent), so the credit note is open in Xero and the refund's budget against the invoice and payment stays consumed. `candidate_provider_id` names the open credit note. | When the cash refund was refused before it was sent (the job's message says `was not written`), fix the cause in Xero (for example the refund account or the original payment), then resume with the same `erp_id`, a new idempotency key and the same credit-note part (`refund_account` and `reference` may change); the runtime copies the frozen credit note and sends only the cash refund. A cause of `xero.period_closed` (a lock date moved after the credit note) keeps the refund's frozen `date`: reopen the period in Xero, then resume; a resume with a new date is refused `accounting.idempotency_conflict`. When Xero refused the cash refund after it was sent (the message says `was refused by Xero`), it is never re-sent for that `erp_id` and a resume sends nothing: ask the runtime operator to complete the cash refund. Or ask the runtime operator to reconcile the refund; once the operator has reconciled it, do not resume it (a resume is refused `accounting.document_exists` naming the linked cash refund). Never resubmit the refund under a new `erp_id`: that writes a second credit note. | not without a change |\n| `accounting.period_closed` | 409 | The document is dated on or before the provider's closing date. Nothing was created. A payment void, delete or update checks the payment's own date (an update that changes the date checks both dates) and an invoice delete the invoice's date; the provider's own closed-period refusal (QuickBooks fault 6200, the Xero lock date) returns this code too. | Re-date the document after the closing date, or reopen the period in the provider, then send it with a new idempotency key. A reversal cannot be re-dated: reopen the period, then send a new void_id, delete_id or change_id. A Xero refund whose credit note is already written ends `accounting.refund_incomplete` instead: reopen the period in Xero, then resume it with its frozen date. | not without a change |\n| `accounting.settings_conflict` | 409 | The settings changed since expected_revision was read. | GET the settings again, reapply the change and resend with the new revision. | not without a change |\n| `tenant.not_active` | 409 | Registration found a retained customer mapping whose status is not active. | Read the same external-ID mapping for recovery. Contact support (the address is in your Console footer) about lifecycle policy; do not change or recycle the customer ID. | not without a change |\n| `tenant.not_found` | 404 | No exact external-ID mapping exists in the authenticated app. | Authorize the customer in the product backend, then register the stable external customer ID. | not without a change |\n| `tenant.registry_unavailable` | 503 | The exact customer registry read or registration could not be confirmed, including an uncertain write response or missing app database binding. | Recover by exact external ID or retry the same registration with a fresh HMAC nonce/timestamp. Never assign another customer ID after an uncertain response. | re-sign first |\n| `authz.tenant_inactive` | 403 | The scoped customer is unavailable for new consent. | Retain the mapping and historical request identities. Ask the operator to resolve lifecycle status; registration cannot reactivate it. | not without a change |\n| `quickbooks.invoice_update_payload_invalid` | 400 | The frozen Invoice edit has invalid request/change identity, source, revision, existing line IDs, CAD totals or supported fields. No job is admitted. | Correct the explicitly approved change before first submission. Preserve any existing body, business key and SyncToken after uncertain admission. | not without a change |\n| `quickbooks.invoice_update_source_mismatch` | 400 | The original Invoice edit names a company that differs from the scoped native QuickBooks connection. No job is admitted. | Inspect the original company and connection mapping. Do not repin or re-key an edit whose provider outcome is uncertain. | not without a change |\n| `payment.invalid_input` | 400 | The linked Payment has invalid positive decimal amounts, native references, Invoice linkage or update selectors. No job is admitted. | Correct the original business input before its first submission. Preserve any existing immutable request and reconcile uncertainty instead of changing its key. | not without a change |\n| `prepayment.invalid_input` | 400 | The QuickBooks prepayment envelope is invalid (amount, native references, company or object type), or names a different company than the connection. No job is admitted. | Correct the original business input before its first submission. Preserve any existing immutable request and reconcile uncertainty instead of changing its key. | not without a change |\n| `quickbooks.adjustment_payload_invalid` | 400 | The source-bound credit, refund, application or void envelope is invalid. No job is admitted. | Use the explicit operation-specific envelope and original native source identity. Never re-key a return whose provider outcome is uncertain. | not without a change |\n| `master.not_found` | 404 | The scoped exact-name or provider-id lookup returned no current record, or the selected ERP mapping does not exist. | Choose a verified provider id or retain the missing mapping for investigation; re-sign reads. | re-sign first |\n| `master.rate_limited` | 429 | The shared provider bucket, serialized read slot or provider response refused this controlled master lookup. | Wait for Retry-After or bounded backoff, then re-sign the same scoped read. | re-sign first |\n| `master.provider_unconfirmed` | 502 | The provider read, native grant, operation configuration or response fields could not be confirmed. No mapping is updated. | Preserve the mapping and command; re-sign one read after backoff and investigate continued refusal. | once, then escalate |\n| `master.ambiguous` | 409 | Exact-name lookup returned multiple provider records; choosing one automatically would make the ERP mapping ambiguous. | Read and bind one explicit verified provider id in the same company. | not without a change |\n| `master.unsupported` | 409 | The provider Item or current tax definition is outside the supported bounded master-data shape or effective-rate rules. | Use a supported current definition and verified provider id; do not invent rates. | not without a change |\n| `master.connection_unconfirmed` | 409 | The scoped QuickBooks connection, live native grant or company binding could not be confirmed before this master operation. | Refresh the selected connection and confirm its exact company before retrying. | not without a change |\n| `master.identity_changed` | 409 | The company or native token generation changed during the controlled read. Returned provider evidence is discarded. | Re-read the selected connection and re-sign the original scoped read. | re-sign first |\n| `master.reconciliation_mismatch` | 409 | The explicit provider id does not match the pending immutable command fields, ERP identity or advancing update version. | Investigate the original command and provider evidence; do not change its identity to retry. | not without a change |\n| `master.mapping_conflict` | 409 | A stable provider binding, pending command or concurrent revision prevents the requested local master binding. | Read the current mapping and reconcile its exact pending command before changing any fields. | not without a change |\n| `master.invalid_command` | 400 | Master admission requires one strict immutable command whose command id, entity, recipe and requested object identity agree. No job is created. | Correct the command envelope before preparing and submitting a new reviewed request. | not without a change |\n| `master.company_mismatch` | 409 | The frozen master command company differs from the current scoped QuickBooks connection company at admission. No job is created. | Select the intended connection and verify the company before submitting this command. | not without a change |\n| `master.invalid_query` | 400 | The master lookup or mapping read contains unknown or duplicate query keys. No provider HTTP or local update is attempted. | Use one tenant_id and one documented selector, then sign a fresh request. | not without a change |\n| `usage.window_too_dense` | 422 | The bounded job-usage window contains more than 10000 retained jobs or 200 provider/operation groups. No partial counts are returned. | Choose a shorter window_minutes and send a freshly signed request. | not without a change |\n| `financial_write_tax_declaration_missing` | 400 | Invoice admission requires tax_declarations with exactly one declaration for every provider sales line; the sibling or a line declaration is missing. No job is created. | Add every required tax declaration, then re-sign and resubmit the corrected request. | not without a change |\n| `financial_write_tax_payload_invalid` | 400 | The Invoice-only create payload is malformed: provider-native customer/item/tax references are missing, declarations are invalid, a line is declared taxable but no approved TaxRate line has a positive percentage and a nonzero base, automatic customer/items inputs are present, or the Invoice contains Id, SyncToken or sparse update selectors. No job is created. | Use existing QuickBooks references in the selected company, remove helper inputs and update selectors, correct the document or declarations (a line taxable at 0% is zero_rated or exempt), then re-sign and resubmit. | not without a change |\n| `financial_write_tax_path_unsupported` | 400 | Invoice admission received request TxnTaxDetail, a calculation mode other than TaxExcluded, or a line other than top-level SalesItemLineDetail. No job is created. | Use the supported TaxExcluded sales-line calculation path, then re-sign and resubmit the corrected request. | not without a change |\n| `hmac.signature_invalid` | 401 | Any failure in signature verification: a missing or malformed `X-IR-App-Id` / `X-IR-Key-Id` / `X-IR-Nonce` / `X-IR-Signature` / `X-IR-Timestamp`, a timestamp more than 300s from the runtime's clock, a nonce outside 22–64 characters, an unknown or revoked key, or a signature that does not match. These are deliberately indistinguishable so the response cannot be used to enumerate valid app/key pairs. | Re-derive the canonical payload (see the signing contract) and check it against the published HMAC test vectors, verify the app and key are active, and check your clock. The runtime records the specific reason in its own logs against your `request_id`. | not without a change |\n| `hmac.nonce_reused` | 401 | The `X-IR-Nonce` on this request has already been accepted. Nonces are single-use; this is the replay defence working as designed. | Never retry a signed request byte-for-byte. Generate a fresh nonce and timestamp and re-sign. See “Retrying a 429” — this is the error a naive retry after a quota 429 produces. | re-sign first |\n| `rate_limit.shield_shed` | 429 | The pre-authentication shield, keyed on client IP address. It runs before HMAC verification and exists to shed floods, not to express the product contract. | Wait out `Retry-After` (the full window, 60s), add jitter, resend. Because the decision happens before authentication, the nonce was not consumed. **Byte-identical replay is only safe inside the 300s signature timestamp window** — roughly four `Retry-After` cycles. Past that the original `X-IR-Timestamp` falls outside the window and you get `401 hmac.signature_invalid`, which is indistinguishable from a signing bug. Re-sign if you have been backing off for more than a couple of minutes. | safe to replay |\n| `rate_limit.quota_exceeded` | 429 | The per-application quota, keyed on the authenticated `app_id`. It is evaluated AFTER HMAC verification. | Wait out `Retry-After`, add jitter, and **re-sign with a fresh nonce and timestamp**. The rejected request already consumed its nonce, so replaying it verbatim returns `401 hmac.nonce_reused`. | re-sign first |\n| `authz.ip_not_allowed` | 403 | The service key you signed with is restricted to a set of IP ranges, and the address this request arrived from is not in any of them. Evaluated AFTER signature verification, so it never reveals whether a key exists. It also fires when the runtime cannot determine your source address at all, in which case a restricted key refuses every request rather than silently dropping the restriction. | Send from an allowlisted address, or ask your platform operator to widen the key's allowed IP ranges (they can read the exact address the request arrived from off your `request_id`). Retrying from the same place fails identically. The rejected request already consumed its nonce, so any retry must be re-signed with a fresh nonce and timestamp. | not without a change |\n| `authz.provider_not_enabled` | 403 | The provider named in `provider_key` is not enabled for your application. | Ask your platform operator to enable the provider for the application. | not without a change |\n| `authz.tenant_mismatch` | 403 | The `tenant_id` is not a tenant of the authenticated application. | Send a `tenant_id` that belongs to your app. A tenant of another application is never visible to you, by design. | not without a change |\n| `connection.not_found` | 404 | The connection id, its provider (`provider_key`) or its company/organisation identity is not present in the authenticated app and tenant scope. The runtime deliberately returns the same response for a foreign company identity. | Check the connection, tenant, provider_key and QuickBooks company or Xero organisation ids before re-signing the request. | not without a change |\n| `connection.recovery_pending` | 409 | A Xero disconnect was refused because unresolved financial writes (in-doubt invoice or adjustment writes, or prepared master-data commands) exist on this live connection. Disconnecting now would block the operator recovery that settles them. The body carries counts per kind only. | Retry the same idempotency key after the runtime operator has resolved the writes, or after a few minutes if they are still being swept. | re-sign first |\n| `calendar.grant_not_found` | 404 | The Calendar grant id is not present in the authenticated app and tenant scope. Foreign grant ids are deliberately indistinguishable from unknown ids. | Check the tenant and grant ids before re-signing the request. | not without a change |\n| `calendar.resource_not_found` | 404 | The Calendar resource binding id is not present in the authenticated app and tenant scope. Foreign resource ids are deliberately indistinguishable from unknown ids. | List the scoped grant's current resources and use a returned resource id. | not without a change |\n| `calendar.page_not_found` | 404 | The Calendar page id is not present in the authenticated app and tenant scope. Foreign page ids are deliberately indistinguishable from unknown ids. | Use the page URL from the completed Calendar job manifest, or start a new root read if it was lost. | not without a change |\n| `calendar.continuation_not_found` | 404 | The opaque Calendar continuation handle is absent from the authenticated app and tenant scope or does not identify a retained page traversal. | Start a new root Calendar discovery or event read; do not substitute or guess another traversal handle. | not without a change |\n| `calendar.invalid_input` | 400 | The Calendar discovery or event-read payload does not match the strict operation contract, identity binding, page-size limit or event-window rules. | Correct the request fields and immutable grant or resource identity, then re-sign and submit a new request. | not without a change |\n| `calendar.unsupported_representation` | 400 | The Calendar event read requests a representation that the runtime does not preserve truthfully; only series-and-exceptions is supported. | Use the series-and-exceptions representation and submit a newly signed event-read request. | not without a change |\n| `calendar.invalid_continuation` | 400 | The retained Calendar continuation state no longer validates against its protected scope, operation, query or bounded private-state schema. | Discard the continuation handle and start a new root Calendar discovery or event read. | not without a change |\n| `calendar.resource_denied` | 403 | Persisted Calendar grant, principal, registration, credential or resource identity does not match the scoped binding required by the request. | Do not substitute public ids across grants or tenants. Fetch current scoped status and resource metadata before starting a new operation. | not without a change |\n| `calendar.resource_detached` | 403 | The Calendar resource binding exists in the authenticated scope but has already been detached and cannot authorize a provider read. | List the grant's current resources and select an active binding before starting another read. | not without a change |\n| `calendar.grant_revoked` | 403 | The persisted Calendar grant is disconnected or revoked, so it cannot authorize discovery or event reads. | Reconnect the Calendar account and repeat discovery before selecting resources or reading events. | not without a change |\n| `calendar.grant_disabled` | 403 | The Calendar grant or its application provider configuration is disabled for discovery and event reads. | Ask the platform operator to enable Calendar access, then fetch grant status before retrying. | not without a change |\n| `calendar.insufficient_scopes` | 403 | The Calendar token or application policy does not include every scope required by the requested capability. | Reconnect with the required Calendar scopes, then repeat discovery before starting provider reads. | not without a change |\n| `calendar.reconnect_required` | 409 | The Calendar connection or token lifecycle is not currently active enough to authorize provider discovery or reads. | Reconnect the Calendar account, then fetch current grant status and repeat discovery before retrying. | not without a change |\n| `calendar.generation_changed` | 409 | The persisted Calendar callback or token generation no longer matches the generation captured by this request or resource binding. | Fetch current grant status, repeat discovery and create a new explicit selection or read request. | not without a change |\n| `calendar.selection_changed` | 409 | A selection or detach retry no longer names the same resource binding, grant generation or idempotent intent. | Fetch the current selected-resource list. Preserve the original idempotency key only for an exact retry; otherwise start a new explicit intent. | not without a change |\n| `calendar.page_pending` | 409 | The scoped Calendar page exists, but its owning job has not completed and published the matching immutable result manifest. | Poll the owning job until it completes, then fetch the page URL from that job's result manifest. | re-sign first |\n| `calendar.page_expired` | 410 | The authenticated Calendar page traversal reached its fixed root expiry or its retained payload was pruned. | Start a new root Calendar discovery or event read; page access cannot extend or revive the traversal. | not without a change |\n| `calendar.discovery_expired` | 410 | The Calendar discovery page is older than the bounded selection-proof window and can no longer authorize a resource choice. | Run Calendar discovery again and select the resource from the newly returned discovery page. | not without a change |\n| `calendar.continuation_expired` | 410 | The Calendar continuation belongs to a root traversal whose fixed expiry elapsed or whose retained private provider state was pruned. | Start a new root Calendar discovery or event read; the expired continuation cannot be renewed or replayed. | not without a change |\n| `calendar.state_unavailable` | 503 | The runtime cannot safely interpret the persisted Calendar lifecycle or authorization state. | Retry once with a freshly signed request, then escalate with the request id. | once, then escalate |\n| `oauth.lifecycle_busy` | 409 | A callback exchange, token refresh, reconnect, provider execution or a different disconnect request currently owns this connection's durable OAuth lifecycle generation. | Wait briefly, then re-sign and retry. For disconnect, retain the original idempotency key. | re-sign first |\n| `oauth.disconnect_retryable` | 503 | The provider release (Intuit revocation, or removal of the Xero organisation's connection) or the local disconnected projection did not complete. Also returned while a pending Xero connect has reserved the same Xero connection, and for every Xero disconnect while the runtime's Xero client credentials are not configured. The encrypted retry material remains fenced from callback, refresh and provider execution paths. | Re-sign and retry with the same disconnect idempotency key. Escalate if one retry still fails. | once, then escalate |\n| `request.payload_too_large` | 413 | The raw request body exceeded the `/v1` body limit. Enforced before authentication, so it fires without the body ever being hashed. | Send a smaller body. Chunking at the transport layer does not help — the limit is on the request, not on a single frame. | not without a change |\n| `request.validation_failed` | 400 | The request did not match the operation's declared schema for its body, query, path, header or cookie parameters — a missing or empty required field, a wrong type, or a query parameter repeated where one value is expected. Raised by the shared validation hook before the handler runs, so no side effect has occurred. Properties the schema does not declare are IGNORED rather than rejected, so sending extra fields is not what caused this. A body that is not parseable JSON is rejected EARLIER, by the framework, and returns `400 text/plain` instead — see “Errors that are not problem+json”. | Read the `errors` array: each entry names the offending `field`, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`). Fix the request and resend; on a signed route, re-sign it. Switch on the top-level `code` — `errors[].code` is a validator diagnostic label and is not stable. The list is capped at 20 entries, so a fixed request may surface further ones. | not without a change |\n| `payload_too_large` | 400 | On `POST /v1/operations/execute`, the serialized `payload` field exceeded the maximum job-input size. Distinct from `request.payload_too_large`, which is the whole-body limit at a different layer. | Reduce `payload`, or reference bulk data out of band. | not without a change |\n| `idempotency_key_required` | 400 | The requested operation has `risk_level = financial` and no idempotency key was supplied in either `idempotency_key` or the `Idempotency-Key` header. | Supply a stable key derived from the business event, not a fresh UUID per attempt. See “Idempotency keys”. | not without a change |\n| `connect.return_url_not_allowed` | 400 | `return_url` is unparseable, is not `https`, or its scheme+host is not an exact match in the application's configured callback allowlist. Suffix matching is deliberately not used. | Use an allowlisted return URL, or add its origin under Return URLs on your app page in the Console (My apps). | not without a change |\n| `connect.scopes_not_permitted` | 400 | The requested `scopes` are not a subset of the scopes configured for this provider, or the provider uses a fixed scope set (Xero) and `scopes` differs from it. | Request a narrower scope set. For a fixed-scope provider, omit `scopes` or send exactly its scope set. | not without a change |\n| `connect.provider_not_configured` | 503 | The runtime is not configured for this provider in this environment (for example, its OAuth client credentials are missing). No connect session or authorization URL is created. | Do not retry automatically. Contact the runtime operator. | not without a change |\n| `quickbooks.consent_frozen` | 409 | New production QuickBooks consent is temporarily paused while the provider authorization boundary is reviewed. No connect session or authorization URL is created. | Do not retry automatically. Wait for an operator notice before starting a new QuickBooks Connect or Reconnect ceremony. | not without a change |\n| `connect.session_not_found` | 410 | The connect session does not exist, has expired, was already completed, or its token did not match. The four are collapsed into one response on purpose — distinguishing them would let a caller probe session state. | Start a new connect session. | not without a change |\n| `sync_profile.not_found` | 404 | No sync profile with that id is reachable for the authenticated application and tenant. A profile belonging to another tenant reads as not-found rather than forbidden. | Check `sync_profile_id` and `tenant_id`. | not without a change |\n| `mapping.unknown_object_type` | 400 | The dry-run could not shape a provider payload because the object type stored **on the sync profile** is not one the provider adapter knows. This is a stored-configuration problem, not a problem with the request body. | Have the operator correct the sync profile. Changing the request will not help. | not without a change |\n| `recipe_not_found` | 404 | No recipe is deployed for the `recipe_key` + `recipe_version` pair supplied. | Use a deployed pair. Recipe versions are pinned deliberately so a runtime deploy cannot silently change the steps you asked for. | not without a change |\n| `operation_admission_mismatch` | 400 | The requested provider or object type conflicts with the deployed recipe, or the recipe's operation is associated with a different provider in the catalog. No job is created or published. | Use the exact provider and object type declared by the deployed recipe. If the catalog association is wrong, have an operator correct the runtime configuration rather than changing the request. | not without a change |\n| `operation_app_not_permitted` | 403 | The authenticated runtime app is not permitted to admit this recipe. Recipe product labels are bound explicitly to routable runtime app ids, and shared recipes still require a routable app. | Use a recipe permitted for the authenticated app. Do not retry under another tenant or alter the recipe version to bypass this application boundary. | not without a change |\n| `recipe_version_retired` | 409 | The requested or replayed recipe version is still registered for historical inspection but is below the minimum safe version for that recipe. | Submit a new job using the minimum version named in the response. Do not replay the retired job unchanged. | not without a change |\n| `xero.invoice_payload_invalid` | 400 | A Xero invoice admission did not carry exactly one immutable invoice command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the invoice through POST /v1/accounting/operations. | not without a change |\n| `xero.payment_payload_invalid` | 400 | A Xero payment admission did not carry exactly one immutable payment command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the payment through POST /v1/accounting/operations. | not without a change |\n| `xero.credit_note_payload_invalid` | 400 | A Xero credit note admission did not carry exactly one immutable credit note command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the credit memo through POST /v1/accounting/operations. | not without a change |\n| `xero.allocation_payload_invalid` | 400 | A Xero credit allocation admission did not carry exactly one immutable allocation command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the credit application through POST /v1/accounting/operations. | not without a change |\n| `xero.refund_payload_invalid` | 400 | A Xero refund admission did not carry exactly one immutable two-step refund command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the refund through POST /v1/accounting/operations. | not without a change |\n| `xero.payment_delete_payload_invalid` | 400 | A Xero payment delete admission did not carry exactly one immutable delete command matching the requested object, or its payment ERP id is not the runtime's own linked Xero payment. The neutral accounting API builds this command; it is never sent by a product backend. | Send the payment void or delete through POST /v1/accounting/operations, naming the payment's own erp_id. | not without a change |\n| `xero.prepayment_payload_invalid` | 400 | A Xero prepayment admission did not carry exactly one immutable prepayment command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the prepayment through POST /v1/accounting/operations. | not without a change |\n| `xero.prepayment_allocation_payload_invalid` | 400 | A Xero prepayment allocation admission did not carry exactly one immutable allocation command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the prepayment application through POST /v1/accounting/operations. | not without a change |\n| `xero.prepayment_allocation_delete_payload_invalid` | 400 | A Xero prepayment allocation delete admission did not carry exactly one immutable delete command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend. | Send the prepayment unapply through POST /v1/accounting/operations. | not without a change |\n| `xero.scope_missing` | 409 | The Xero connection was consented before the operation needed a scope it now needs (a prepayment create needs accounting.banktransactions), so its grant lacks it. `missing_scopes` lists them, space-separated. Refused before any job exists; nothing was sent. A product backend sees it as `provider_detail` of accounting.reconnect_required (Xero prepayments are admitted only through the neutral API). | Reconnect the connection (the reconnect asks for the full current scope set), then resend the same request. | not without a change |\n| `xero.invoice_company_mismatch` | 409 | The connection now points at a different Xero organisation than the one the invoice was prepared for. | Check the connection's organisation, then send the invoice again with a new idempotency key. | not without a change |\n| `invoice_identity_unavailable` | 409 | Invoice admission cannot establish the destination provider company. | Connect the intended company and resubmit. Historical writes without immutable identity require operator review; never re-key an uncertain write. | not without a change |\n| `idempotency_key_conflict` | 409 | The idempotency key belongs to a job with a different payload, company, recipe version, operation, or object identity, or historical payload evidence is unavailable. | Use the original payload and identity exactly. An existing internal invoice is immutable; do not change keys to bypass a conflict. Missing historical evidence requires operator review. | not without a change |\n| `operation_not_enabled` | 403 | The provider operation exists in the catalog but is not enabled. Financial-write operations ship disabled and stay disabled until the operation is enabled for your app. | Ask your platform operator to enable the operation. This is a governance gate, not a transient condition. | not without a change |\n| `operation_not_attestable` | 403 | The provider operation is disabled AND can never be enabled: no safety attestation may cover it, so the governance gate that would enable it refuses too. Distinct from `operation_not_enabled`, which is a state an operator can change. | Do not ask an operator to enable this operation and do not retry — both the enable endpoint and the sign-off route refuse the request. Treat it as permanently unavailable for this runtime version. | not without a change |\n| `tenant_operation_not_enabled` | 403 | The provider operation is enabled in the catalog, but an explicit tenant Kill or Disarm override refuses it for your tenant. An absent tenant override inherits global enablement; financial writes still require current same-app policy qualification. | Ask your platform operator to review the explicit tenant Kill or Disarm override. New tenants do not require an Arm step. Distinct from `operation_not_enabled`, which means the operation is disabled for everyone — this is a per-tenant governance gate, not a transient condition. | not without a change |\n| `tenant_enablement_unavailable` | 503 | The runtime could not read the per-tenant enablement state for this operation, so it refused rather than guess. This is an infrastructure condition, not a permission decision. | Retry with a FRESHLY SIGNED request (new `X-IR-Nonce` + `X-IR-Timestamp`) and ordinary backoff. Replaying the identical signed request fails `hmac.nonce_reused`: this refusal is raised inside the handler, after the auth middleware has already consumed the nonce. No `Retry-After` header is sent on this response. If it persists, escalate — the runtime is deliberately refusing financial writes while the rollout state is unknown. | re-sign first |\n| `sync_job.not_found` | 404 | No sync job with that id exists for the authenticated application and tenant. Cross-tenant reads are reported as not-found. | Check the job id and `tenant_id`. | not without a change |\n| `calendar.replay_requires_new_read` | 409 | The source job belongs to a paginated Google Calendar read. Its continuation and authorization state are managed by the Calendar page flow, so generic sync-job replay is refused without creating a replacement job. | Start a new root Calendar read with a newly signed request. Do not replay the stored page job or reuse its continuation as a generic sync-job input. | not without a change |\n| `sync_job.not_replayable` | 409 | The job cannot be replayed, or publication of its replacement was deferred or refused. Causes include missing recipe/input, unavailable historical Invoice identity, a payload conflict, or an unconfirmed delivery outcome. The original dead-letter record stays open when replacement publication is not confirmed. | If instance contains a replacement job polling URL, poll that job and inspect its failure code; do not repeatedly replay the original or create an Invoice with a new key. Escalate terminal or unconfirmed outcomes to your platform operator for reconciliation. A deferred replacement may recover through the publication sweep. | not without a change |\n| `refund.replay_requires_continue` | 409 | The source job is a Xero compound refund. A generic replay could re-run its steps out of order or beside a cash refund whose outcome is unknown, so it is refused without creating a replacement job, whatever the source job's status. | Resume the refund through `POST /v1/accounting/operations` with the same `erp_id`, a new idempotency key and the same credit-note part, or ask the runtime operator to reconcile it. Never resubmit it under a new `erp_id`. | not without a change |\n| `sync_job.replay_in_progress` | 409 | The source job is still queued or processing. Its step results are not stable yet, so creating a replay could run beside the original or skip a verifier whose latest run later fails. | Wait until the source job reaches a terminal status, fetch it again, then submit a newly signed replay request. Do not create a second operation while the original is active. | re-sign first |\n| `request.route_not_found` | 404 | No route matched the path + method, and every path-scoped middleware let the request through. The runtime does not emit `405`: a wrong method on a known path produces this code — but only after the path's middleware runs, because middleware is bound to the PATH, not the method. On a signed path, an UNSIGNED wrong-method request therefore surfaces as `401 hmac.signature_invalid` (and an over-limit one as `429`) before the router's not-found can render. | Check the path and method against the spec. A resource that exists but is not yours produces a resource-specific 404 (`sync_job.not_found`, `sync_profile.not_found`) instead, so this code always means the URL or verb is wrong. | not without a change |\n| `internal_error` | 500 | An unhandled fault in the runtime. This is also what a request carrying an unrecognised `app_id` currently produces on some paths. | Retry once with backoff, then escalate quoting `request_id`. For non-idempotent operations, confirm whether the write landed before retrying — a 500 does not mean nothing happened. Do not loop: a persistent 500 is an incident, not congestion. | once, then escalate |\n\n### Errors that are not problem+json\n\nOne response does not carry the envelope, and one carries it only sometimes. A client that\nassumes `problem+json` universally will mis-handle the first:\n\n- **A request body that is not parseable JSON** returns `400` as `text/plain`, with the body\n  `Malformed JSON in request body`. It is rejected by the framework before the schema layer\n  runs, so it carries no `code` and no `errors` — unlike a well-formed body that merely fails\n  the schema, which is `400 request.validation_failed` in the normal envelope. (Schema\n  failures were listed in this section in earlier releases, as an `application/json` body\n  with no `code`. They are no longer an exception; see above. Unrouted paths and unhandled\n  faults were also listed here as `text/plain` in earlier releases; they now carry the\n  envelope — `404 request.route_not_found` and `500 internal_error` in the table above.)\n- **The browser OAuth callbacks** report a *provider-side* failure by redirecting (`302`)\n  to your `return_url` with error parameters in the query string, because the user agent at\n  that point is a human's browser and a JSON body would be a dead end. They do still return\n  a problem body — `410 connect.session_not_found` — when the session itself is unknown,\n  expired, already completed, or its token does not match, so a browser can land on raw\n  JSON. Handle both.\n\nOnly errors from the operations in this document are listed.\n\n## Rate limits and the 429 contract\n\nTwo independent inbound limiters guard `/v1`. They are distinguished by the\nproblem-details `code` on the `429` body, so a client can tell which one it hit:\n\n- **`rate_limit.shield_shed`** — a pre-authentication shield keyed on the **client IP\n  address**, at **15000 requests per 60 seconds**. It runs before HMAC verification and\n  exists to shed floods, not to express the product contract.\n- **`rate_limit.quota_exceeded`** — the per-application quota keyed on the\n  **authenticated `app_id`**, at **3000 requests per 60 seconds**. This is the number to\n  design against.\n\n**The counters are per Cloudflare location, not global.** Cloudflare's rate-limiting\nprimitive keeps a separate, eventually-consistent counter in each location that serves\nyour traffic, so the effective worldwide ceiling is roughly `limit × the number of\nlocations your traffic reaches` — a caller spread across many regions can exceed the\nnominal number before seeing a `429`. Treat both limits as DoS and runaway-loop\nceilings rather than a billing-grade quota; do not build metering, billing or capacity\nplanning on them.\n\n### Retrying a 429 — the two codes differ\n\n**`rate_limit.shield_shed` is safe to replay byte-for-byte.** It is decided before\nauthentication, so the request's nonce (if it carried one) was not consumed. Wait out\n`Retry-After`, add jitter, and resend the identical signed request.\n\n**`rate_limit.quota_exceeded` is not.** Read on — this is the one that surprises people.\n\nA `rate_limit.quota_exceeded` rejection happens **after** HMAC verification, which means\nthe request's `X-IR-Nonce` has already been consumed. Replaying the identical signed\nrequest therefore returns `401 hmac.nonce_reused` — not a second `429`, and not a\nsuccess. **Every retry MUST be re-signed with a fresh `X-IR-Nonce` and a fresh\n`X-IR-Timestamp`.** Apply jittered backoff so a fleet of retrying clients does not\nresynchronize onto the next window boundary.\n\n### Response headers\n\nA `429` carries `Retry-After`. Its value is the **full window length in seconds (60)**,\nnot the time remaining in the current window: the underlying rate-limiting binding\nreports only whether a request was allowed and exposes no reset timestamp, so any\nseconds-until-reset value the runtime printed would be a guess presented as a fact. One\nfull window is correct-or-conservative instead.\n\n`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` are deliberately **not**\nsent. The binding exposes no remaining-quota or reset value to report, and because the\ncounters are per-location any single global remaining-quota number would be actively\nmisleading. The limit actually in force is stated in the `429` problem-details body,\nwhere it cannot be mistaken for a standardised live counter.\n\n### Paths that are not rate limited\n\n`GET /v1/health` (liveness probe), `GET /v1/connections/oauth/callback` (the end-user\nbrowser redirect, where a `429` would\nbreak a human's connect flow irrecoverably) and `GET /v1/openapi.json` (SDK codegen and\nCI tooling) are exempt by design. Provider webhook ingest lives outside `/v1`, under\n`/webhooks/*`, and is not covered by these limiters at all.\n\n## Idempotency keys\n\n`POST /v1/operations/execute` accepts an idempotency key, in the `idempotency_key` body\nfield or the `Idempotency-Key` header. The body field wins if both are sent.\n\n**It is required for any operation whose risk level is financial.** Omitting it there is a\n`400 idempotency_key_required` — the runtime will not accept a money-moving instruction it\ncannot recognise as a repeat.\n\n### What it guarantees\n\nAn original (non-replay) job claims its key **per connection**. Re-sending the same\nrequest identity returns `202` with the **original** `job_id` instead of creating another\noriginal job.\n\nFor Invoice CREATE, `same request identity` is deliberately strict: the canonical payload\nfingerprint, pinned QuickBooks company, recipe key and version, operation, object type, and\ninternal object id must all match the original job. Missing historical fingerprint evidence\nor any mismatch returns `409 idempotency_key_conflict`; no replacement job is created.\n\nFor non-Invoice operations, the route compares the recipe, operation, object type, and\ninternal object id, but it does not currently fingerprint the payload. Never reuse their\nkeys with changed input: a matching route identity returns the original job.\n\nFor the request-id-proven Invoice CREATE path, the runtime also persists a stable\nprovider-side request token derived from the full Invoice identity and caller key. Bounded\nautomatic recovery reuses that token. If the original provider-call clock is too old,\nmissing, or invalid, the runtime fails closed for operator reconciliation instead of\npromising that an automatic reissue is still duplicate-safe.\n\n### Choosing and preserving a key\n\nDerive keys from the business event they represent (an invoice id plus the operation, say),\nand deliberately exclude the recipe version. Never derive one from a retry counter, a\ntimestamp, or a fresh UUID per attempt — a per-attempt UUID switches route-level\ndeduplication off while looking like it is on.\n\nOnce a key has been issued, preserve it exactly, including a historical version suffix.\nDo not move a queued or historical v1/v2 attempt to v3 by changing its key, payload, or\nrecipe version. Reconcile an ambiguous prior attempt with an operator instead of creating\na new financial identity.\n\nScope and lifetime, precisely:\n\n- **The original-job claim is scoped to the connection.** The same key against a different\n  `connection_id` is a different route-level identity. That does not bypass downstream\n  business-object reservations, which also bind app, tenant, provider, object type, and\n  internal object identity.\n- **The route claim lasts for the original job's retained lifetime.** There is no separate\n  expiry window. If retention later removes that job, the route index no longer carries\n  the claim, but a downstream business-object reservation may still exist. Never infer\n  from job retention alone that an old financial event is safe to resubmit or re-key.\n- **Operator replays preserve rather than free the identity.** A replay job is excluded from\n  the original-job unique index so it can copy the original key and metadata. The original\n  job remains the public key claimant while retained, and Invoice replay also shares the\n  persisted reservation and payload fingerprint. This is not permission to submit a new\n  business event under that key.\n- **Without a key there is no route-level deduplication.** For non-financial operations the\n  field is optional, and every call without one creates a distinct job; operation-specific\n  downstream reservation rules may still prevent a duplicate provider object.\n\nA key does not make retrying free at the HTTP layer: the signed request still needs a fresh\nnonce and timestamp on every attempt (see “Retrying a 429”). Idempotency and replay\nprotection are separate mechanisms solving separate problems.\n\n## Enum stability\n\nAdding a member to a closed enum is a breaking change, which on this API costs a URL\nversion bump. Most enums here describe state machines the runtime owns and expects to\nextend, so they are declared **extensible**: marked `x-ir-enum-open: true` and carrying an\n“Extensible enum” note in their description.\n\n**If a field is marked extensible, tolerating unknown values is part of the contract.** Map\na value you do not recognise to an explicit “unrecognised” case and carry on; do not throw,\nand do not reject the response. A client that hard-fails on an unseen member has no claim\nwhen a MINOR release adds one. Language enums that raise on an unknown value — a PHP backed\nenum's `from()`, a Python `Enum(value)`, a strict schema validator — are the usual way this\nbreaks; prefer the non-raising variant at the boundary.\n\nAn enum with no such marking is closed, and gaining a member would be a MAJOR release.\nToday every enum in this spec is extensible.","x-ir-error-codes":[{"code":"accounting.invalid_input","status":400,"cause":"A neutral accounting request has an unknown or duplicate query parameter, a tax_code mapping or bind row without `treatment`, or `treatment` on any other kind. For a QuickBooks payment or refund it can also mean a ref was left out (payment: payment_method and/or deposit_account; refund: payment_method only) before omitting it is enabled for the app; the job fails on its first attempt, its error message names the field, and nothing was sent.","action":"Fix the request; send only documented neutral fields. When `errors` is present, each entry names the offending field (bind rows as `body.bindings[i].treatment`). For an omitted payment or refund ref, send the named field under a new idempotency key; the job can still be refused for another expanded case (for example a refund with mixed funding, decided after QuickBooks reads).","retry":"never"},{"code":"accounting.connection_not_found","status":404,"cause":"The connection id does not exist for this tenant, or it is not an accounting connection.","action":"Read the tenant's accounting connection from GET /v1/accounting/providers.","retry":"never"},{"code":"accounting.no_accounting_connection","status":409,"cause":"The tenant has no active accounting connection, or the named one is not connected.","action":"Have the tenant connect an accounting provider, then retry.","retry":"never"},{"code":"accounting.connection_exists","status":409,"cause":"POST /v1/connections/connect-session for an accounting provider while the customer already has an active connection to a different accounting provider. `connection_id` and `provider_key` name it.","action":"Disconnect the existing accounting connection first (POST /v1/connections/{id}/disconnect), then start the new connection. Documents stay in the old provider.","retry":"never"},{"code":"accounting.multiple_accounting_connections","status":409,"cause":"The tenant has more than one active accounting connection; neutral calls need exactly one.","action":"Disconnect the connection the tenant no longer uses.","retry":"never"},{"code":"accounting.provider_unavailable","status":503,"cause":"The accounting provider is not enabled for the app, or a provider read through the connection coordinator was not confirmed. A refused bind may carry `reason`: pending_change (a create or update of the ERP record, or another change of its mapping, is in progress) or connection_changed (the connection was reconnected during the bind).","action":"Retry later with a fresh signature; escalate if it persists.","retry":"once-then-escalate"},{"code":"accounting.snapshot_unsupported","status":422,"cause":"A record snapshot was requested for a provider that does not support snapshots yet (QuickBooks and Xero today).","action":"Use the paged records list and match routes for this connection.","retry":"never"},{"code":"accounting.snapshot_refresh_too_soon","status":409,"cause":"A new snapshot (a `refresh`, or a restart after a failed one) was requested less than 15 minutes after the last one on the same connection. `snapshot_id` names that snapshot.","action":"Use the named snapshot, or retry after `Retry-After`.","retry":"safe"},{"code":"accounting.snapshot_capacity","status":503,"cause":"Snapshot storage for the app database is at its row ceiling.","action":"Retry after `Retry-After`, or match without a snapshot.","retry":"safe"},{"code":"accounting.snapshot_not_enabled","status":403,"cause":"Record snapshots are not enabled for this app or tenant yet.","action":"Use the paged records list and match routes; ask the runtime operator to enable snapshots.","retry":"never"},{"code":"accounting.snapshot_refused","status":400,"cause":"The snapshot's background job was not admitted. The status is the admission's own; `provider_detail` names the underlying refusal.","action":"Read `provider_detail`; retry only if `Retry-After` is present.","retry":"once-then-escalate"},{"code":"accounting.snapshot_conflict","status":409,"cause":"Another snapshot request for the same connection and record type won a race.","action":"Retry the request; it returns the running snapshot.","retry":"safe"},{"code":"accounting.snapshot_not_found","status":404,"cause":"No snapshot has been taken for this connection and record type, or (for `source: snapshot` or a `q` search) none is ready and usable.","action":"Start one with POST .../snapshots, or match and list with `source: live`.","retry":"never"},{"code":"accounting.snapshot_not_ready","status":409,"cause":"A records match or list asked for a snapshot (or `auto`) while a snapshot pull for this connection and record type is still running, and no ready one is usable. `snapshot_id` names the pull.","action":"Wait for the snapshot job's `sync_job.completed` webhook, or retry after `Retry-After`; or use `source: live`.","retry":"safe"},{"code":"accounting.bind_job_unsupported","status":422,"cause":"A bind job was requested for a record type other than customer or item, or for a provider without bind jobs (QuickBooks and Xero today).","action":"Bind other record types with POST .../records/{entity}/bind, 25 rows per call.","retry":"never"},{"code":"accounting.bind_job_too_large","status":413,"cause":"A bind job was sent more than 5,000 rows.","action":"Split the bindings into jobs of at most 5,000 rows, one after another.","retry":"never"},{"code":"accounting.bind_job_in_progress","status":409,"cause":"A bind job is already pending or running for this connection. `job_id` names it when known.","action":"Wait for that job's `sync_job.completed` or `sync_job.dead_lettered` webhook, then start the next one.","retry":"safe"},{"code":"accounting.bind_job_not_enabled","status":403,"cause":"Bind jobs are not enabled for this app or tenant yet.","action":"Use POST .../records/{entity}/bind; ask the runtime operator to enable bind jobs.","retry":"never"},{"code":"accounting.bind_job_refused","status":400,"cause":"The bind job's background job was not admitted. The status is the admission's own; `provider_detail` names the underlying refusal.","action":"Read `provider_detail`; retry only if `Retry-After` is present.","retry":"once-then-escalate"},{"code":"accounting.bind_job_not_found","status":404,"cause":"No bind job with this job id exists for this connection and record type, or its results passed the 7-day retention.","action":"Check the job id from the start response or the webhook.","retry":"never"},{"code":"accounting.match_too_many","status":422,"cause":"A live records match was sent more than 100 records (`max_records`); 1,000 are allowed only against a ready snapshot.","action":"Send at most 100 records per live call, or take a snapshot first.","retry":"never"},{"code":"accounting.rate_limited","status":429,"cause":"The connection's provider quota is exhausted for this read.","action":"Wait for Retry-After, then re-sign and retry.","retry":"after-resign"},{"code":"accounting.reference_not_found","status":404,"cause":"No provider record matches the provider reference or exact name.","action":"Pick a reference from the provider's current records.","retry":"never"},{"code":"accounting.reference_invalid","status":409,"cause":"The provider record exists but cannot be used for this kind (wrong account type, inactive, ambiguous or unsupported).","action":"Choose an active record of the right type. `reason` says which: inactive or not_usable_for_kind.","retry":"never"},{"code":"accounting.mapping_not_found","status":404,"cause":"No mapping exists for this ERP code on the tenant's accounting connection.","action":"Create the mapping with PUT before using the code.","retry":"never"},{"code":"accounting.mapping_conflict","status":409,"cause":"The provider record is already bound to another ERP id, or the record is ambiguous or unsupported, or changed during verification. Binding an ERP id that is already bound to a different provider record re-binds it on every provider.","action":"Read `reason`: bound_to_other_record (`bound_erp_id` holds the record: unmap or rebind that ERP id, or choose another record), record_already_bound (no longer returned by a bind; keep `bound_provider_ref` or bind the ERP id to it), not_usable_for_kind or ambiguous (choose another record). `reason` is absent only when the runtime cannot tell.","retry":"never"},{"code":"accounting.unsupported_change","status":409,"cause":"The requested change is not supported, e.g. deleting a company-bound customer or item mapping, or a QuickBooks item update whose `type` differs from the provider item (refused at submit, or as the job's error if the item changed in between). Also the job's error for a payment void, delete or update that the runtime or the provider does not allow: a payment over several invoices, a credit application, a payment named by a refund written through this API, a QuickBooks delete of a voided payment, a QuickBooks payment in a bank deposit (fault 6540), a QuickBooks payment update whose amount QuickBooks still refuses against the payment's charges (fault 6000; a lowered amount normally lowers the invoice application with it), or a Xero payment that is reconciled or part of a batch payment; and for a QuickBooks invoice void or delete after the other one succeeded. Nothing was written.","action":"Rebind the record to the correct provider reference instead. For a payment reversal, fix the cause in the provider first (remove the payment from its QuickBooks deposit, or unreconcile it or remove it from its Xero batch), then send a new void_id, delete_id or change_id with a new idempotency key. For a refused payment update amount, refresh the payment and review it with a person first. A payment named by a runtime refund cannot be reversed, and a voided QuickBooks payment is not deleted. A repeat of the same reversal of an already voided or deleted payment is not refused: it completes with no write.","retry":"never"},{"code":"accounting.mapping_missing","status":409,"cause":"A neutral write names an ERP customer, item or code with no usable mapping for the connection. `mapping_kind`, `mapping_erp_code` and `mapping_state` say what to map; `mapping_state` `inactive` or `drifted` means the mapped provider record was archived, deleted or is no longer usable for the kind.","action":"Map the named record or code (PUT .../mappings/{kind}/{erp_code}), then resend the same request.","retry":"never"},{"code":"accounting.tax_mismatch","status":409,"cause":"The ERP's expected tax does not match the mapped tax codes: a tax_lines component is not in the code, or the tax lines do not add up to total_tax. Also returned when the provider's verification refuses the tax.","action":"Recompute tax from the mapped codes, or send per-rate tax_lines; use a new idempotency_key for the corrected request.","retry":"never"},{"code":"accounting.idempotency_conflict","status":409,"cause":"The idempotency_key was already used on this connection for a different neutral request, or the connection now points at a different provider company than when the key was first used.","action":"Resend the original request unchanged, or use a new idempotency_key for a new request.","retry":"never"},{"code":"accounting.capability_unsupported","status":422,"cause":"The connected provider does not support this operation or currency yet (QuickBooks: CAD home currency only), or the request needs a QuickBooks expanded case (for example a payment across several invoices, a refund with mixed funding, or an expanded invoice update) that is not qualified for the app (nothing was written). Xero answers it for accounting.payment.update (Xero has no payment update: delete the payment, then create a new one under a new erp_id) and accounting.invoice.delete (Xero deletes draft invoices only: void instead).","action":"Read GET /v1/accounting/providers capabilities before offering the action. Do not retry an expanded-case refusal; it succeeds only after the case is qualified for the app.","retry":"never"},{"code":"accounting.operation_in_progress","status":409,"cause":"A customer or item write for this ERP id, another update, void or delete of the same invoice, or another void, delete or update of the same payment (for a refund: of the payment it returns), or another apply or unapply of the same prepayment, is still pending at the provider or awaiting operator reconciliation.","action":"Poll the earlier operation to completion, then resend.","retry":"once-then-escalate"},{"code":"accounting.revision_conflict","status":409,"cause":"The provider document no longer matches the ERP's expected_revision or before-state (for a master record: the runtime has no current revision for it). Nothing was changed.","action":"Refresh the record (for a master record, PUT the same mapping again), review the provider's current state, then resend with a new idempotency key.","retry":"never"},{"code":"accounting.invoice_has_payment","status":409,"cause":"A Xero void of an invoice that has a payment (or a credit) applied. Xero voids only invoices with nothing applied, so nothing was sent. QuickBooks voids and deletes such an invoice and leaves the payment unapplied, so it does not return this code. On an async job it is the job's `error.code`; a provider that checks at admission returns it synchronously.","action":"Remove or unapply the payment in the provider first, then resend the void with a new idempotency key; or credit the invoice (accounting.credit_memo.create) instead.","retry":"never"},{"code":"accounting.amount_exceeded","status":409,"cause":"The provider refused the amount: a refund over what was paid on the invoice, or a returned or credited line over what remains of the original line. A prepayment apply over the invoice's open balance or the prepayment's remaining credit answers it too; on QuickBooks the runtime refuses it before anything is sent.","action":"Refresh the invoice (or the prepayment) and reduce the amount.","retry":"never"},{"code":"accounting.document_unlinked","status":409,"cause":"The ERP document (an invoice, or the payment a refund returns) has no verified provider document on this connection, or the invoice has two different ones. With `reason` mapping_changed: the ERP prepayment of an accounting.prepayment.apply was re-bound to another credit after the request was accepted; its job is cancelled (or, on a whole-job replay of its failed job, no replay job is created). Nothing was sent.","action":"Create the invoice through the runtime first, or link one it created through quickbooks(), then resend. For mapping_changed, resend the apply under a new idempotency_key: it uses the credit the ERP prepayment holds now.","retry":"never"},{"code":"accounting.link_conflict","status":409,"cause":"The invoice is already linked with a different line map, or its provider invoice is linked to another ERP id. Nothing was changed.","action":"Send the line map that is already recorded, or contact support (the address is in your Console footer) to correct it.","retry":"never"},{"code":"accounting.operation_disabled","status":403,"cause":"The native operation this request translates to is disabled, killed or not permitted for the app or tenant, or the request carries an optional field (`invoice.reference`) whose provider capability is disabled. `provider_detail` carries the native code.","action":"Do not retry; the operation must be enabled by the operator.","retry":"never"},{"code":"accounting.reconnect_required","status":409,"cause":"The connection's grant lacks a scope this operation needs: it was consented before the operation needed it (Xero: accounting.prepayment.create needs accounting.banktransactions). `missing_scopes` lists them, space-separated; `provider_detail` carries the native code. Refused before any job exists; nothing was sent.","action":"Ask the customer to reconnect the connection (the same connect-session flow as Reconnect), then resend the same request unchanged. GET /v1/accounting/connections/{id}/capabilities shows the operation with reason reconnect_required until then.","retry":"never"},{"code":"accounting.provider_refused","status":400,"cause":"Native admission refused the translated request for a reason without a neutral equivalent. `provider_detail` carries the native code; the HTTP status is the native status.","action":"Read provider_detail; fix the request or escalate.","retry":"never"},{"code":"accounting.operation_not_found","status":404,"cause":"No neutral accounting operation with this job id exists for the tenant.","action":"Use the job_id returned by POST /v1/accounting/operations.","retry":"never"},{"code":"accounting.record_type_disabled","status":409,"cause":"Syncing this record type is turned off in the connection's accounting settings. `record_type` names it.","action":"Turn the record type on with PUT /v1/accounting/connections/{id}/settings if it should sync, then resend.","retry":"never"},{"code":"accounting.before_sync_start","status":409,"cause":"A new document was created before the connection's sync_start_date (by default the day the provider was connected), judged by erp_created_at when the request sends it and by the document date otherwise. Writes to a document already linked on the connection (update, void, delete, payment changes) are never refused by the sync start.","action":"If the document was created on or after the sync start date but dated earlier, resend it with erp_created_at (the same idempotency key is accepted). Otherwise keep it in the ERP only, or move sync_start_date earlier with PUT /v1/accounting/connections/{id}/settings after matching or linking the provider's existing records of that period, then resend.","retry":"never"},{"code":"accounting.document_exists","status":409,"cause":"The provider already has a document with this number (voided ones count), or a customer with this name or an item with this code (archived ones count), or a Xero refund resumed after an operator reconciled it by linking a cash refund made by hand, or a create that names the erp_id of an invoice or payment that was deleted (an erp_id is never reused after a delete; create it under a new erp_id). On QuickBooks a customer's name must also be unused by any vendor or employee, compared without regard to letter case; the title names the record type and id that uses it. Nothing was created. `candidate_provider_id` names the existing document when known (for a name, only a customer or item the ERP could bind). It may come back synchronously from POST /v1/accounting/operations or as the job's error.","action":"Renumber the document in the ERP and send it with a new idempotency key. For a name, rename the record in the ERP, or bind the existing customer or item (PUT .../mappings) instead of creating. Only when the existing invoice was created by the runtime through quickbooks() on this connection can PUT .../documents/invoice/{erp_id}/link adopt it instead; an invoice entered directly in the provider cannot be linked. For a reconciled Xero refund, `candidate_provider_id` names the cash refund the operator linked: the refund is complete, so record it and do not resend.","retry":"never"},{"code":"accounting.write_uncertain","status":409,"cause":"A provider write may have reached the provider but was not confirmed, or the provider holds a document that differs from what was sent. The runtime never re-sends it; the ERP record stays fenced until an operator reconciles it.","action":"Do not resend. Check the record in the provider and ask the runtime operator to reconcile the command.","retry":"never"},{"code":"accounting.refund_incomplete","status":409,"cause":"A Xero refund is written in two steps: a credit note against the invoice, then a cash refund of that credit note. The credit note was written and verified; the cash refund was proved not written (it was refused, or refused before it was sent), so the credit note is open in Xero and the refund's budget against the invoice and payment stays consumed. `candidate_provider_id` names the open credit note.","action":"When the cash refund was refused before it was sent (the job's message says `was not written`), fix the cause in Xero (for example the refund account or the original payment), then resume with the same `erp_id`, a new idempotency key and the same credit-note part (`refund_account` and `reference` may change); the runtime copies the frozen credit note and sends only the cash refund. A cause of `xero.period_closed` (a lock date moved after the credit note) keeps the refund's frozen `date`: reopen the period in Xero, then resume; a resume with a new date is refused `accounting.idempotency_conflict`. When Xero refused the cash refund after it was sent (the message says `was refused by Xero`), it is never re-sent for that `erp_id` and a resume sends nothing: ask the runtime operator to complete the cash refund. Or ask the runtime operator to reconcile the refund; once the operator has reconciled it, do not resume it (a resume is refused `accounting.document_exists` naming the linked cash refund). Never resubmit the refund under a new `erp_id`: that writes a second credit note.","retry":"never"},{"code":"accounting.period_closed","status":409,"cause":"The document is dated on or before the provider's closing date. Nothing was created. A payment void, delete or update checks the payment's own date (an update that changes the date checks both dates) and an invoice delete the invoice's date; the provider's own closed-period refusal (QuickBooks fault 6200, the Xero lock date) returns this code too.","action":"Re-date the document after the closing date, or reopen the period in the provider, then send it with a new idempotency key. A reversal cannot be re-dated: reopen the period, then send a new void_id, delete_id or change_id. A Xero refund whose credit note is already written ends `accounting.refund_incomplete` instead: reopen the period in Xero, then resume it with its frozen date.","retry":"never"},{"code":"accounting.settings_conflict","status":409,"cause":"The settings changed since expected_revision was read.","action":"GET the settings again, reapply the change and resend with the new revision.","retry":"never"},{"code":"tenant.not_active","status":409,"cause":"Registration found a retained customer mapping whose status is not active.","action":"Read the same external-ID mapping for recovery. Contact support (the address is in your Console footer) about lifecycle policy; do not change or recycle the customer ID.","retry":"never"},{"code":"tenant.not_found","status":404,"cause":"No exact external-ID mapping exists in the authenticated app.","action":"Authorize the customer in the product backend, then register the stable external customer ID.","retry":"never"},{"code":"tenant.registry_unavailable","status":503,"cause":"The exact customer registry read or registration could not be confirmed, including an uncertain write response or missing app database binding.","action":"Recover by exact external ID or retry the same registration with a fresh HMAC nonce/timestamp. Never assign another customer ID after an uncertain response.","retry":"after-resign"},{"code":"authz.tenant_inactive","status":403,"cause":"The scoped customer is unavailable for new consent.","action":"Retain the mapping and historical request identities. Ask the operator to resolve lifecycle status; registration cannot reactivate it.","retry":"never"},{"code":"quickbooks.invoice_update_payload_invalid","status":400,"cause":"The frozen Invoice edit has invalid request/change identity, source, revision, existing line IDs, CAD totals or supported fields. No job is admitted.","action":"Correct the explicitly approved change before first submission. Preserve any existing body, business key and SyncToken after uncertain admission.","retry":"never"},{"code":"quickbooks.invoice_update_source_mismatch","status":400,"cause":"The original Invoice edit names a company that differs from the scoped native QuickBooks connection. No job is admitted.","action":"Inspect the original company and connection mapping. Do not repin or re-key an edit whose provider outcome is uncertain.","retry":"never"},{"code":"payment.invalid_input","status":400,"cause":"The linked Payment has invalid positive decimal amounts, native references, Invoice linkage or update selectors. No job is admitted.","action":"Correct the original business input before its first submission. Preserve any existing immutable request and reconcile uncertainty instead of changing its key.","retry":"never"},{"code":"prepayment.invalid_input","status":400,"cause":"The QuickBooks prepayment envelope is invalid (amount, native references, company or object type), or names a different company than the connection. No job is admitted.","action":"Correct the original business input before its first submission. Preserve any existing immutable request and reconcile uncertainty instead of changing its key.","retry":"never"},{"code":"quickbooks.adjustment_payload_invalid","status":400,"cause":"The source-bound credit, refund, application or void envelope is invalid. No job is admitted.","action":"Use the explicit operation-specific envelope and original native source identity. Never re-key a return whose provider outcome is uncertain.","retry":"never"},{"code":"master.not_found","status":404,"cause":"The scoped exact-name or provider-id lookup returned no current record, or the selected ERP mapping does not exist.","action":"Choose a verified provider id or retain the missing mapping for investigation; re-sign reads.","retry":"after-resign"},{"code":"master.rate_limited","status":429,"cause":"The shared provider bucket, serialized read slot or provider response refused this controlled master lookup.","action":"Wait for Retry-After or bounded backoff, then re-sign the same scoped read.","retry":"after-resign"},{"code":"master.provider_unconfirmed","status":502,"cause":"The provider read, native grant, operation configuration or response fields could not be confirmed. No mapping is updated.","action":"Preserve the mapping and command; re-sign one read after backoff and investigate continued refusal.","retry":"once-then-escalate"},{"code":"master.ambiguous","status":409,"cause":"Exact-name lookup returned multiple provider records; choosing one automatically would make the ERP mapping ambiguous.","action":"Read and bind one explicit verified provider id in the same company.","retry":"never"},{"code":"master.unsupported","status":409,"cause":"The provider Item or current tax definition is outside the supported bounded master-data shape or effective-rate rules.","action":"Use a supported current definition and verified provider id; do not invent rates.","retry":"never"},{"code":"master.connection_unconfirmed","status":409,"cause":"The scoped QuickBooks connection, live native grant or company binding could not be confirmed before this master operation.","action":"Refresh the selected connection and confirm its exact company before retrying.","retry":"never"},{"code":"master.identity_changed","status":409,"cause":"The company or native token generation changed during the controlled read. Returned provider evidence is discarded.","action":"Re-read the selected connection and re-sign the original scoped read.","retry":"after-resign"},{"code":"master.reconciliation_mismatch","status":409,"cause":"The explicit provider id does not match the pending immutable command fields, ERP identity or advancing update version.","action":"Investigate the original command and provider evidence; do not change its identity to retry.","retry":"never"},{"code":"master.mapping_conflict","status":409,"cause":"A stable provider binding, pending command or concurrent revision prevents the requested local master binding.","action":"Read the current mapping and reconcile its exact pending command before changing any fields.","retry":"never"},{"code":"master.invalid_command","status":400,"cause":"Master admission requires one strict immutable command whose command id, entity, recipe and requested object identity agree. No job is created.","action":"Correct the command envelope before preparing and submitting a new reviewed request.","retry":"never"},{"code":"master.company_mismatch","status":409,"cause":"The frozen master command company differs from the current scoped QuickBooks connection company at admission. No job is created.","action":"Select the intended connection and verify the company before submitting this command.","retry":"never"},{"code":"master.invalid_query","status":400,"cause":"The master lookup or mapping read contains unknown or duplicate query keys. No provider HTTP or local update is attempted.","action":"Use one tenant_id and one documented selector, then sign a fresh request.","retry":"never"},{"code":"usage.window_too_dense","status":422,"cause":"The bounded job-usage window contains more than 10000 retained jobs or 200 provider/operation groups. No partial counts are returned.","action":"Choose a shorter window_minutes and send a freshly signed request.","retry":"never"},{"code":"financial_write_tax_declaration_missing","status":400,"cause":"Invoice admission requires tax_declarations with exactly one declaration for every provider sales line; the sibling or a line declaration is missing. No job is created.","action":"Add every required tax declaration, then re-sign and resubmit the corrected request.","retry":"never"},{"code":"financial_write_tax_payload_invalid","status":400,"cause":"The Invoice-only create payload is malformed: provider-native customer/item/tax references are missing, declarations are invalid, a line is declared taxable but no approved TaxRate line has a positive percentage and a nonzero base, automatic customer/items inputs are present, or the Invoice contains Id, SyncToken or sparse update selectors. No job is created.","action":"Use existing QuickBooks references in the selected company, remove helper inputs and update selectors, correct the document or declarations (a line taxable at 0% is zero_rated or exempt), then re-sign and resubmit.","retry":"never"},{"code":"financial_write_tax_path_unsupported","status":400,"cause":"Invoice admission received request TxnTaxDetail, a calculation mode other than TaxExcluded, or a line other than top-level SalesItemLineDetail. No job is created.","action":"Use the supported TaxExcluded sales-line calculation path, then re-sign and resubmit the corrected request.","retry":"never"},{"code":"hmac.signature_invalid","status":401,"cause":"Any failure in signature verification: a missing or malformed `X-IR-App-Id` / `X-IR-Key-Id` / `X-IR-Nonce` / `X-IR-Signature` / `X-IR-Timestamp`, a timestamp more than 300s from the runtime's clock, a nonce outside 22–64 characters, an unknown or revoked key, or a signature that does not match. These are deliberately indistinguishable so the response cannot be used to enumerate valid app/key pairs.","action":"Re-derive the canonical payload (see the signing contract) and check it against the published HMAC test vectors, verify the app and key are active, and check your clock. The runtime records the specific reason in its own logs against your `request_id`.","retry":"never"},{"code":"hmac.nonce_reused","status":401,"cause":"The `X-IR-Nonce` on this request has already been accepted. Nonces are single-use; this is the replay defence working as designed.","action":"Never retry a signed request byte-for-byte. Generate a fresh nonce and timestamp and re-sign. See “Retrying a 429” — this is the error a naive retry after a quota 429 produces.","retry":"after-resign"},{"code":"rate_limit.shield_shed","status":429,"cause":"The pre-authentication shield, keyed on client IP address. It runs before HMAC verification and exists to shed floods, not to express the product contract.","action":"Wait out `Retry-After` (the full window, 60s), add jitter, resend. Because the decision happens before authentication, the nonce was not consumed. **Byte-identical replay is only safe inside the 300s signature timestamp window** — roughly four `Retry-After` cycles. Past that the original `X-IR-Timestamp` falls outside the window and you get `401 hmac.signature_invalid`, which is indistinguishable from a signing bug. Re-sign if you have been backing off for more than a couple of minutes.","retry":"safe"},{"code":"rate_limit.quota_exceeded","status":429,"cause":"The per-application quota, keyed on the authenticated `app_id`. It is evaluated AFTER HMAC verification.","action":"Wait out `Retry-After`, add jitter, and **re-sign with a fresh nonce and timestamp**. The rejected request already consumed its nonce, so replaying it verbatim returns `401 hmac.nonce_reused`.","retry":"after-resign"},{"code":"authz.ip_not_allowed","status":403,"cause":"The service key you signed with is restricted to a set of IP ranges, and the address this request arrived from is not in any of them. Evaluated AFTER signature verification, so it never reveals whether a key exists. It also fires when the runtime cannot determine your source address at all, in which case a restricted key refuses every request rather than silently dropping the restriction.","action":"Send from an allowlisted address, or ask your platform operator to widen the key's allowed IP ranges (they can read the exact address the request arrived from off your `request_id`). Retrying from the same place fails identically. The rejected request already consumed its nonce, so any retry must be re-signed with a fresh nonce and timestamp.","retry":"never"},{"code":"authz.provider_not_enabled","status":403,"cause":"The provider named in `provider_key` is not enabled for your application.","action":"Ask your platform operator to enable the provider for the application.","retry":"never"},{"code":"authz.tenant_mismatch","status":403,"cause":"The `tenant_id` is not a tenant of the authenticated application.","action":"Send a `tenant_id` that belongs to your app. A tenant of another application is never visible to you, by design.","retry":"never"},{"code":"connection.not_found","status":404,"cause":"The connection id, its provider (`provider_key`) or its company/organisation identity is not present in the authenticated app and tenant scope. The runtime deliberately returns the same response for a foreign company identity.","action":"Check the connection, tenant, provider_key and QuickBooks company or Xero organisation ids before re-signing the request.","retry":"never"},{"code":"connection.recovery_pending","status":409,"cause":"A Xero disconnect was refused because unresolved financial writes (in-doubt invoice or adjustment writes, or prepared master-data commands) exist on this live connection. Disconnecting now would block the operator recovery that settles them. The body carries counts per kind only.","action":"Retry the same idempotency key after the runtime operator has resolved the writes, or after a few minutes if they are still being swept.","retry":"after-resign"},{"code":"calendar.grant_not_found","status":404,"cause":"The Calendar grant id is not present in the authenticated app and tenant scope. Foreign grant ids are deliberately indistinguishable from unknown ids.","action":"Check the tenant and grant ids before re-signing the request.","retry":"never"},{"code":"calendar.resource_not_found","status":404,"cause":"The Calendar resource binding id is not present in the authenticated app and tenant scope. Foreign resource ids are deliberately indistinguishable from unknown ids.","action":"List the scoped grant's current resources and use a returned resource id.","retry":"never"},{"code":"calendar.page_not_found","status":404,"cause":"The Calendar page id is not present in the authenticated app and tenant scope. Foreign page ids are deliberately indistinguishable from unknown ids.","action":"Use the page URL from the completed Calendar job manifest, or start a new root read if it was lost.","retry":"never"},{"code":"calendar.continuation_not_found","status":404,"cause":"The opaque Calendar continuation handle is absent from the authenticated app and tenant scope or does not identify a retained page traversal.","action":"Start a new root Calendar discovery or event read; do not substitute or guess another traversal handle.","retry":"never"},{"code":"calendar.invalid_input","status":400,"cause":"The Calendar discovery or event-read payload does not match the strict operation contract, identity binding, page-size limit or event-window rules.","action":"Correct the request fields and immutable grant or resource identity, then re-sign and submit a new request.","retry":"never"},{"code":"calendar.unsupported_representation","status":400,"cause":"The Calendar event read requests a representation that the runtime does not preserve truthfully; only series-and-exceptions is supported.","action":"Use the series-and-exceptions representation and submit a newly signed event-read request.","retry":"never"},{"code":"calendar.invalid_continuation","status":400,"cause":"The retained Calendar continuation state no longer validates against its protected scope, operation, query or bounded private-state schema.","action":"Discard the continuation handle and start a new root Calendar discovery or event read.","retry":"never"},{"code":"calendar.resource_denied","status":403,"cause":"Persisted Calendar grant, principal, registration, credential or resource identity does not match the scoped binding required by the request.","action":"Do not substitute public ids across grants or tenants. Fetch current scoped status and resource metadata before starting a new operation.","retry":"never"},{"code":"calendar.resource_detached","status":403,"cause":"The Calendar resource binding exists in the authenticated scope but has already been detached and cannot authorize a provider read.","action":"List the grant's current resources and select an active binding before starting another read.","retry":"never"},{"code":"calendar.grant_revoked","status":403,"cause":"The persisted Calendar grant is disconnected or revoked, so it cannot authorize discovery or event reads.","action":"Reconnect the Calendar account and repeat discovery before selecting resources or reading events.","retry":"never"},{"code":"calendar.grant_disabled","status":403,"cause":"The Calendar grant or its application provider configuration is disabled for discovery and event reads.","action":"Ask the platform operator to enable Calendar access, then fetch grant status before retrying.","retry":"never"},{"code":"calendar.insufficient_scopes","status":403,"cause":"The Calendar token or application policy does not include every scope required by the requested capability.","action":"Reconnect with the required Calendar scopes, then repeat discovery before starting provider reads.","retry":"never"},{"code":"calendar.reconnect_required","status":409,"cause":"The Calendar connection or token lifecycle is not currently active enough to authorize provider discovery or reads.","action":"Reconnect the Calendar account, then fetch current grant status and repeat discovery before retrying.","retry":"never"},{"code":"calendar.generation_changed","status":409,"cause":"The persisted Calendar callback or token generation no longer matches the generation captured by this request or resource binding.","action":"Fetch current grant status, repeat discovery and create a new explicit selection or read request.","retry":"never"},{"code":"calendar.selection_changed","status":409,"cause":"A selection or detach retry no longer names the same resource binding, grant generation or idempotent intent.","action":"Fetch the current selected-resource list. Preserve the original idempotency key only for an exact retry; otherwise start a new explicit intent.","retry":"never"},{"code":"calendar.page_pending","status":409,"cause":"The scoped Calendar page exists, but its owning job has not completed and published the matching immutable result manifest.","action":"Poll the owning job until it completes, then fetch the page URL from that job's result manifest.","retry":"after-resign"},{"code":"calendar.page_expired","status":410,"cause":"The authenticated Calendar page traversal reached its fixed root expiry or its retained payload was pruned.","action":"Start a new root Calendar discovery or event read; page access cannot extend or revive the traversal.","retry":"never"},{"code":"calendar.discovery_expired","status":410,"cause":"The Calendar discovery page is older than the bounded selection-proof window and can no longer authorize a resource choice.","action":"Run Calendar discovery again and select the resource from the newly returned discovery page.","retry":"never"},{"code":"calendar.continuation_expired","status":410,"cause":"The Calendar continuation belongs to a root traversal whose fixed expiry elapsed or whose retained private provider state was pruned.","action":"Start a new root Calendar discovery or event read; the expired continuation cannot be renewed or replayed.","retry":"never"},{"code":"calendar.state_unavailable","status":503,"cause":"The runtime cannot safely interpret the persisted Calendar lifecycle or authorization state.","action":"Retry once with a freshly signed request, then escalate with the request id.","retry":"once-then-escalate"},{"code":"oauth.lifecycle_busy","status":409,"cause":"A callback exchange, token refresh, reconnect, provider execution or a different disconnect request currently owns this connection's durable OAuth lifecycle generation.","action":"Wait briefly, then re-sign and retry. For disconnect, retain the original idempotency key.","retry":"after-resign"},{"code":"oauth.disconnect_retryable","status":503,"cause":"The provider release (Intuit revocation, or removal of the Xero organisation's connection) or the local disconnected projection did not complete. Also returned while a pending Xero connect has reserved the same Xero connection, and for every Xero disconnect while the runtime's Xero client credentials are not configured. The encrypted retry material remains fenced from callback, refresh and provider execution paths.","action":"Re-sign and retry with the same disconnect idempotency key. Escalate if one retry still fails.","retry":"once-then-escalate"},{"code":"request.payload_too_large","status":413,"cause":"The raw request body exceeded the `/v1` body limit. Enforced before authentication, so it fires without the body ever being hashed.","action":"Send a smaller body. Chunking at the transport layer does not help — the limit is on the request, not on a single frame.","retry":"never"},{"code":"request.validation_failed","status":400,"cause":"The request did not match the operation's declared schema for its body, query, path, header or cookie parameters — a missing or empty required field, a wrong type, or a query parameter repeated where one value is expected. Raised by the shared validation hook before the handler runs, so no side effect has occurred. Properties the schema does not declare are IGNORED rather than rejected, so sending extra fields is not what caused this. A body that is not parseable JSON is rejected EARLIER, by the framework, and returns `400 text/plain` instead — see “Errors that are not problem+json”.","action":"Read the `errors` array: each entry names the offending `field`, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`). Fix the request and resend; on a signed route, re-sign it. Switch on the top-level `code` — `errors[].code` is a validator diagnostic label and is not stable. The list is capped at 20 entries, so a fixed request may surface further ones.","retry":"never"},{"code":"payload_too_large","status":400,"cause":"On `POST /v1/operations/execute`, the serialized `payload` field exceeded the maximum job-input size. Distinct from `request.payload_too_large`, which is the whole-body limit at a different layer.","action":"Reduce `payload`, or reference bulk data out of band.","retry":"never"},{"code":"idempotency_key_required","status":400,"cause":"The requested operation has `risk_level = financial` and no idempotency key was supplied in either `idempotency_key` or the `Idempotency-Key` header.","action":"Supply a stable key derived from the business event, not a fresh UUID per attempt. See “Idempotency keys”.","retry":"never"},{"code":"connect.return_url_not_allowed","status":400,"cause":"`return_url` is unparseable, is not `https`, or its scheme+host is not an exact match in the application's configured callback allowlist. Suffix matching is deliberately not used.","action":"Use an allowlisted return URL, or add its origin under Return URLs on your app page in the Console (My apps).","retry":"never"},{"code":"connect.scopes_not_permitted","status":400,"cause":"The requested `scopes` are not a subset of the scopes configured for this provider, or the provider uses a fixed scope set (Xero) and `scopes` differs from it.","action":"Request a narrower scope set. For a fixed-scope provider, omit `scopes` or send exactly its scope set.","retry":"never"},{"code":"connect.provider_not_configured","status":503,"cause":"The runtime is not configured for this provider in this environment (for example, its OAuth client credentials are missing). No connect session or authorization URL is created.","action":"Do not retry automatically. Contact the runtime operator.","retry":"never"},{"code":"quickbooks.consent_frozen","status":409,"cause":"New production QuickBooks consent is temporarily paused while the provider authorization boundary is reviewed. No connect session or authorization URL is created.","action":"Do not retry automatically. Wait for an operator notice before starting a new QuickBooks Connect or Reconnect ceremony.","retry":"never"},{"code":"connect.session_not_found","status":410,"cause":"The connect session does not exist, has expired, was already completed, or its token did not match. The four are collapsed into one response on purpose — distinguishing them would let a caller probe session state.","action":"Start a new connect session.","retry":"never"},{"code":"sync_profile.not_found","status":404,"cause":"No sync profile with that id is reachable for the authenticated application and tenant. A profile belonging to another tenant reads as not-found rather than forbidden.","action":"Check `sync_profile_id` and `tenant_id`.","retry":"never"},{"code":"mapping.unknown_object_type","status":400,"cause":"The dry-run could not shape a provider payload because the object type stored **on the sync profile** is not one the provider adapter knows. This is a stored-configuration problem, not a problem with the request body.","action":"Have the operator correct the sync profile. Changing the request will not help.","retry":"never"},{"code":"recipe_not_found","status":404,"cause":"No recipe is deployed for the `recipe_key` + `recipe_version` pair supplied.","action":"Use a deployed pair. Recipe versions are pinned deliberately so a runtime deploy cannot silently change the steps you asked for.","retry":"never"},{"code":"operation_admission_mismatch","status":400,"cause":"The requested provider or object type conflicts with the deployed recipe, or the recipe's operation is associated with a different provider in the catalog. No job is created or published.","action":"Use the exact provider and object type declared by the deployed recipe. If the catalog association is wrong, have an operator correct the runtime configuration rather than changing the request.","retry":"never"},{"code":"operation_app_not_permitted","status":403,"cause":"The authenticated runtime app is not permitted to admit this recipe. Recipe product labels are bound explicitly to routable runtime app ids, and shared recipes still require a routable app.","action":"Use a recipe permitted for the authenticated app. Do not retry under another tenant or alter the recipe version to bypass this application boundary.","retry":"never"},{"code":"recipe_version_retired","status":409,"cause":"The requested or replayed recipe version is still registered for historical inspection but is below the minimum safe version for that recipe.","action":"Submit a new job using the minimum version named in the response. Do not replay the retired job unchanged.","retry":"never"},{"code":"xero.invoice_payload_invalid","status":400,"cause":"A Xero invoice admission did not carry exactly one immutable invoice command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the invoice through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.payment_payload_invalid","status":400,"cause":"A Xero payment admission did not carry exactly one immutable payment command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the payment through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.credit_note_payload_invalid","status":400,"cause":"A Xero credit note admission did not carry exactly one immutable credit note command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the credit memo through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.allocation_payload_invalid","status":400,"cause":"A Xero credit allocation admission did not carry exactly one immutable allocation command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the credit application through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.refund_payload_invalid","status":400,"cause":"A Xero refund admission did not carry exactly one immutable two-step refund command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the refund through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.payment_delete_payload_invalid","status":400,"cause":"A Xero payment delete admission did not carry exactly one immutable delete command matching the requested object, or its payment ERP id is not the runtime's own linked Xero payment. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the payment void or delete through POST /v1/accounting/operations, naming the payment's own erp_id.","retry":"never"},{"code":"xero.prepayment_payload_invalid","status":400,"cause":"A Xero prepayment admission did not carry exactly one immutable prepayment command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the prepayment through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.prepayment_allocation_payload_invalid","status":400,"cause":"A Xero prepayment allocation admission did not carry exactly one immutable allocation command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the prepayment application through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.prepayment_allocation_delete_payload_invalid","status":400,"cause":"A Xero prepayment allocation delete admission did not carry exactly one immutable delete command matching the requested object. The neutral accounting API builds this command; it is never sent by a product backend.","action":"Send the prepayment unapply through POST /v1/accounting/operations.","retry":"never"},{"code":"xero.scope_missing","status":409,"cause":"The Xero connection was consented before the operation needed a scope it now needs (a prepayment create needs accounting.banktransactions), so its grant lacks it. `missing_scopes` lists them, space-separated. Refused before any job exists; nothing was sent. A product backend sees it as `provider_detail` of accounting.reconnect_required (Xero prepayments are admitted only through the neutral API).","action":"Reconnect the connection (the reconnect asks for the full current scope set), then resend the same request.","retry":"never"},{"code":"xero.invoice_company_mismatch","status":409,"cause":"The connection now points at a different Xero organisation than the one the invoice was prepared for.","action":"Check the connection's organisation, then send the invoice again with a new idempotency key.","retry":"never"},{"code":"invoice_identity_unavailable","status":409,"cause":"Invoice admission cannot establish the destination provider company.","action":"Connect the intended company and resubmit. Historical writes without immutable identity require operator review; never re-key an uncertain write.","retry":"never"},{"code":"idempotency_key_conflict","status":409,"cause":"The idempotency key belongs to a job with a different payload, company, recipe version, operation, or object identity, or historical payload evidence is unavailable.","action":"Use the original payload and identity exactly. An existing internal invoice is immutable; do not change keys to bypass a conflict. Missing historical evidence requires operator review.","retry":"never"},{"code":"operation_not_enabled","status":403,"cause":"The provider operation exists in the catalog but is not enabled. Financial-write operations ship disabled and stay disabled until the operation is enabled for your app.","action":"Ask your platform operator to enable the operation. This is a governance gate, not a transient condition.","retry":"never"},{"code":"operation_not_attestable","status":403,"cause":"The provider operation is disabled AND can never be enabled: no safety attestation may cover it, so the governance gate that would enable it refuses too. Distinct from `operation_not_enabled`, which is a state an operator can change.","action":"Do not ask an operator to enable this operation and do not retry — both the enable endpoint and the sign-off route refuse the request. Treat it as permanently unavailable for this runtime version.","retry":"never"},{"code":"tenant_operation_not_enabled","status":403,"cause":"The provider operation is enabled in the catalog, but an explicit tenant Kill or Disarm override refuses it for your tenant. An absent tenant override inherits global enablement; financial writes still require current same-app policy qualification.","action":"Ask your platform operator to review the explicit tenant Kill or Disarm override. New tenants do not require an Arm step. Distinct from `operation_not_enabled`, which means the operation is disabled for everyone — this is a per-tenant governance gate, not a transient condition.","retry":"never"},{"code":"tenant_enablement_unavailable","status":503,"cause":"The runtime could not read the per-tenant enablement state for this operation, so it refused rather than guess. This is an infrastructure condition, not a permission decision.","action":"Retry with a FRESHLY SIGNED request (new `X-IR-Nonce` + `X-IR-Timestamp`) and ordinary backoff. Replaying the identical signed request fails `hmac.nonce_reused`: this refusal is raised inside the handler, after the auth middleware has already consumed the nonce. No `Retry-After` header is sent on this response. If it persists, escalate — the runtime is deliberately refusing financial writes while the rollout state is unknown.","retry":"after-resign"},{"code":"sync_job.not_found","status":404,"cause":"No sync job with that id exists for the authenticated application and tenant. Cross-tenant reads are reported as not-found.","action":"Check the job id and `tenant_id`.","retry":"never"},{"code":"calendar.replay_requires_new_read","status":409,"cause":"The source job belongs to a paginated Google Calendar read. Its continuation and authorization state are managed by the Calendar page flow, so generic sync-job replay is refused without creating a replacement job.","action":"Start a new root Calendar read with a newly signed request. Do not replay the stored page job or reuse its continuation as a generic sync-job input.","retry":"never"},{"code":"sync_job.not_replayable","status":409,"cause":"The job cannot be replayed, or publication of its replacement was deferred or refused. Causes include missing recipe/input, unavailable historical Invoice identity, a payload conflict, or an unconfirmed delivery outcome. The original dead-letter record stays open when replacement publication is not confirmed.","action":"If instance contains a replacement job polling URL, poll that job and inspect its failure code; do not repeatedly replay the original or create an Invoice with a new key. Escalate terminal or unconfirmed outcomes to your platform operator for reconciliation. A deferred replacement may recover through the publication sweep.","retry":"never"},{"code":"refund.replay_requires_continue","status":409,"cause":"The source job is a Xero compound refund. A generic replay could re-run its steps out of order or beside a cash refund whose outcome is unknown, so it is refused without creating a replacement job, whatever the source job's status.","action":"Resume the refund through `POST /v1/accounting/operations` with the same `erp_id`, a new idempotency key and the same credit-note part, or ask the runtime operator to reconcile it. Never resubmit it under a new `erp_id`.","retry":"never"},{"code":"sync_job.replay_in_progress","status":409,"cause":"The source job is still queued or processing. Its step results are not stable yet, so creating a replay could run beside the original or skip a verifier whose latest run later fails.","action":"Wait until the source job reaches a terminal status, fetch it again, then submit a newly signed replay request. Do not create a second operation while the original is active.","retry":"after-resign"},{"code":"request.route_not_found","status":404,"cause":"No route matched the path + method, and every path-scoped middleware let the request through. The runtime does not emit `405`: a wrong method on a known path produces this code — but only after the path's middleware runs, because middleware is bound to the PATH, not the method. On a signed path, an UNSIGNED wrong-method request therefore surfaces as `401 hmac.signature_invalid` (and an over-limit one as `429`) before the router's not-found can render.","action":"Check the path and method against the spec. A resource that exists but is not yours produces a resource-specific 404 (`sync_job.not_found`, `sync_profile.not_found`) instead, so this code always means the URL or verb is wrong.","retry":"never"},{"code":"internal_error","status":500,"cause":"An unhandled fault in the runtime. This is also what a request carrying an unrecognised `app_id` currently produces on some paths.","action":"Retry once with backoff, then escalate quoting `request_id`. For non-idempotent operations, confirm whether the write landed before retrying — a 500 does not mean nothing happened. Do not loop: a persistent 500 is an incident, not congestion.","retry":"once-then-escalate"}]},"servers":[{"url":"https://staging.integrationengine.ca","description":"Sandbox (Intuit sandbox companies)"},{"url":"https://api.integrationengine.ca","description":"Production"},{"url":"http://localhost:8787","description":"Local Wrangler dev"}],"security":[{"HmacSig":[]}],"tags":[{"name":"Tenants","description":"App-authenticated exact customer mapping registration and recovery."},{"name":"Health","description":"Liveness probe."},{"name":"Connections","description":"Tenant ↔ provider connection lifecycle."},{"name":"Mappings","description":"Tenant field mappings, draft/validate/publish lifecycle."},{"name":"Usage","description":"Retained job creation cohorts and current outcomes; provider HTTP attempts unavailable."},{"name":"QuickBooks","description":"Scoped company master-data reads and stable ERP mappings."},{"name":"SyncJobs","description":"Inspect sync job status and steps."},{"name":"Webhooks","description":"Signed HTTPS deliveries the runtime sends to your receiver. See the webhook guide for verification, retries and deduplication."}],"components":{"securitySchemes":{"HmacSig":{"type":"apiKey","in":"header","name":"X-IR-Signature","description":"base64url HMAC-SHA256 signature. Compute it server-side from the raw service secret; never send that secret as a header or expose it to a browser. See the getting-started guide for the canonical string."}},"schemas":{"CalendarPageManifest":{"type":"object","properties":{"kind":{"type":"string","enum":["calendar-page"]},"version":{"type":"number","enum":[1]},"page_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"page_url":{"type":"string","minLength":1},"expires_at":{"type":"integer","minimum":0}},"required":["kind","version","page_id","page_url","expires_at"],"additionalProperties":false},"CalendarDiscoveryInitialPayload":{"type":"object","properties":{"grant_id":{"type":"string","minLength":1},"page_size":{"type":"integer","minimum":1,"maximum":10,"default":10}},"required":["grant_id"],"additionalProperties":false},"CalendarDiscoveryResumePayload":{"type":"object","properties":{"grant_id":{"type":"string","minLength":1},"continuation_handle":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["grant_id","continuation_handle"],"additionalProperties":false},"CalendarEventsInitialPayload":{"type":"object","properties":{"grant_id":{"type":"string","minLength":1},"resource_id":{"type":"string","minLength":1},"representation":{"type":"string","enum":["series-and-exceptions"]},"time_min":{"type":"string","minLength":1},"time_max":{"type":"string","minLength":1},"page_size":{"type":"integer","minimum":1,"maximum":10,"default":10}},"required":["grant_id","resource_id","representation","time_min","time_max"],"additionalProperties":false},"CalendarEventsResumePayload":{"type":"object","properties":{"grant_id":{"type":"string","minLength":1},"resource_id":{"type":"string","minLength":1},"continuation_handle":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["grant_id","resource_id","continuation_handle"],"additionalProperties":false},"SyncJobWebhookSnapshot":{"type":"object","properties":{"id":{"type":"string","description":"The sync job id. GET /v1/sync-jobs/{id} for the current state."},"status":{"type":"string","description":"Terminal job status at occurred_at: completed, dead_lettered or manually_resolved (failed is reserved). A snapshot, not a live read."},"operation_key":{"type":"string","description":"For example quickbooks.invoice.create."},"object_type":{"type":["string","null"]},"connection_id":{"type":"string"},"provider_key":{"type":"string","description":"For example quickbooks."},"external_object_id":{"type":["string","null"],"description":"The provider's id for the object, once linked."},"attempt_count":{"type":"integer","description":"Sync-job attempts. Not the webhook delivery attempt."},"last_error_code":{"type":["string","null"],"description":"Closed-taxonomy job error code, or null. No free-text error message is sent."},"created_at":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp with milliseconds, e.g. 2026-08-02T14:31:07.482Z."},"completed_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp with milliseconds, e.g. 2026-08-02T14:31:07.482Z."}},"required":["id","status","operation_key","object_type","connection_id","provider_key","external_object_id","attempt_count","last_error_code","created_at","completed_at"]},"SyncJobWebhookPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["sync_job.completed","sync_job.failed","sync_job.dead_lettered","sync_job.resolved"],"x-ir-enum-open":true,"description":"The sync-job event. sync_job.failed is reserved and does not fire today.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"data":{"type":"object","properties":{"sync_job":{"$ref":"#/components/schemas/SyncJobWebhookSnapshot"}},"required":["sync_job"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","data"]},"AccountingStatusDocument":{"type":"object","properties":{"provider_key":{"type":"string","description":"For example quickbooks or xero."},"document_type":{"type":"string","enum":["invoice","payment","credit_application"],"x-ir-enum-open":true,"description":"Neutral document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"erp_id":{"type":"string","description":"Your id for the document, as you sent it."},"provider_id":{"type":"string"},"revision":{"type":["string","null"],"description":"Opaque. Send it as expected_revision on the next write. Null only for a deleted document."},"provider_account_id":{"type":"string"},"status":{"type":"string","description":"Provider status, e.g. open, partially_paid, paid, voided, deleted; treat an unknown value as not writable."},"currency":{"type":["string","null"]},"total_amount":{"type":["string","null"],"description":"Decimal string, e.g. 113.00."},"balance":{"type":["string","null"],"description":"Open balance as a decimal string; null for a payment."},"provider_updated_at":{"type":"string"},"observed_at":{"type":"string"}},"required":["provider_key","document_type","erp_id","provider_id","revision","provider_account_id","status","currency","total_amount","balance","provider_updated_at","observed_at"]},"AccountingDocumentStatusWebhookPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["accounting.document.status_changed"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"callback_epoch":{"type":"integer","description":"The connection's authorization generation when the change was recorded."},"data":{"type":"object","properties":{"connection_id":{"type":"string"},"sequence":{"type":"integer","description":"Increases with every change of this document. Ignore an event whose sequence is not higher than one you already applied."},"document":{"$ref":"#/components/schemas/AccountingStatusDocument"}},"required":["connection_id","sequence","document"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","callback_epoch","data"]},"QuickBooksTransactionStatusWebhookPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["quickbooks.transaction.status_changed"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"callback_epoch":{"type":"integer","description":"The connection's authorization generation when the change was recorded."},"data":{"type":"object","properties":{"transaction":{"$ref":"#/components/schemas/QuickBooksTransactionStatus"}},"required":["transaction"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","callback_epoch","data"]},"QuickBooksTransactionStatus":{"type":"object","properties":{"entity_type":{"type":"string","enum":["Invoice","Payment"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"external_id":{"type":"string"},"sync_token":{"type":["string","null"]},"provider_updated_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["open","partially_paid","paid","zero_value","active","voided","deleted"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"customer_ref":{"type":["string","null"]},"currency":{"type":["string","null"]},"total_minor":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991},"balance_minor":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991},"unapplied_minor":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991},"payment_funding":{"type":["string","null"],"enum":["cash","credit_application","mixed",null],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"cash_applied_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"credit_memo_allocations":{"type":"array","items":{"type":"object","properties":{"credit_memo_id":{"type":"string"},"amount_minor":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["credit_memo_id","amount_minor"]}},"payment_allocations":{"type":"array","items":{"type":"object","properties":{"payment_id":{"type":"string"},"amount_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"funding":{"type":["string","null"],"enum":["cash","credit_application","mixed",null],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"cash_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"credit_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"credit_memo_ids":{"type":"array","items":{"type":"string"}}},"required":["payment_id","amount_minor"]}},"allocations":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount_minor":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["invoice_id","amount_minor"]}},"connection_id":{"type":"string"},"provider_key":{"type":"string","enum":["quickbooks"]},"provider_account_id":{"type":"string"},"internal_id":{"type":["string","null"]},"projection_revision":{"type":"integer","exclusiveMinimum":0},"observed_at":{"type":"string","format":"date-time"}},"required":["entity_type","external_id","sync_token","provider_updated_at","status","customer_ref","currency","total_minor","balance_minor","unapplied_minor","payment_allocations","allocations","connection_id","provider_key","provider_account_id","internal_id","projection_revision","observed_at"]},"ConnectionWebhookSnapshot":{"type":"object","properties":{"id":{"type":"string","description":"The connection id. GET /v1/connections/{id} for the authoritative state."},"provider_key":{"type":"string","description":"For example quickbooks or xero."},"status":{"type":"string","enum":["connected","reconnect_required","disconnected"],"x-ir-enum-open":true,"description":"The status the connection moved to, at occurred_at. A snapshot.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"previous_status":{"type":["string","null"],"enum":["connected","reconnect_required","disconnected","disabled",null],"x-ir-enum-open":true,"description":"The status before this change, or null for the connection's first connect.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"reason":{"type":["string","null"],"enum":["invalid_grant","refresh_token_expired","disconnect",null],"x-ir-enum-open":true,"description":"Why it moved: invalid_grant or refresh_token_expired (the provider grant stopped working; the customer must reconnect), disconnect, or null.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["id","provider_key","status","previous_status","reason"]},"MeetingArtifactsWebhookSnapshot":{"type":"object","properties":{"meeting_ref":{"type":"string","description":"The meeting. GET /v1/meetings/connections/{connection_id}/meetings/{meeting_ref}/artifacts for the current answer."},"external_ref":{"type":"string","description":"Your own reference for the meeting."},"connection_id":{"type":"string"},"provider_key":{"type":"string","description":"For example google-meet."},"stage":{"type":"string","enum":["available","final"],"x-ir-enum-open":true,"description":"available: a recording or transcript is ready and more may follow. final: the answer will not change any more (status available or none). At most one event per stage per meeting.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"status":{"type":"string","enum":["available","none"],"x-ir-enum-open":true,"description":"available: at least one file is ready. none: nothing was recorded.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"reason":{"type":["string","null"],"description":"Why status is none: not_recorded_or_not_permitted or processing_timeout. Null otherwise."},"final":{"type":"boolean"},"recordings":{"type":"array","items":{"$ref":"#/components/schemas/MeetingArtifact"}},"transcripts":{"type":"array","items":{"$ref":"#/components/schemas/MeetingArtifact"}},"checked_at":{"type":"string","format":"date-time","description":"When the provider was asked for this answer."}},"required":["meeting_ref","external_ref","connection_id","provider_key","stage","status","reason","final","recordings","transcripts","checked_at"]},"MeetingArtifact":{"type":"object","properties":{"artifact_id":{"type":"string","description":"The provider's id for this recording or transcript."},"state":{"type":"string","enum":["processing","ready"],"x-ir-enum-open":true,"description":"processing: the provider is still making the file. ready: the file exists. Treat an unknown state as processing.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"started_at":{"type":["string","null"],"description":"ISO 8601."},"ended_at":{"type":["string","null"],"description":"ISO 8601."},"view_url":{"type":["string","null"],"description":"A browser link to the file at the provider, once ready. Who can open it follows the organizer's own sharing rules (for Google Meet, their Drive): others see request access."},"provider_file_id":{"type":["string","null"],"description":"The provider's file id (for Google Meet, the Drive file or Google Doc id)."}},"required":["artifact_id","state","started_at","ended_at","view_url","provider_file_id"]},"MeetingArtifactsWebhookPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["meeting.artifacts_ready"],"x-ir-enum-open":true,"description":"Explicit-only: sent only to endpoints that list it.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"data":{"type":"object","properties":{"meeting":{"$ref":"#/components/schemas/MeetingArtifactsWebhookSnapshot"}},"required":["meeting"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","data"]},"ConnectionStatusWebhookPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["connection.connected","connection.reconnect_required","connection.disconnected"],"x-ir-enum-open":true,"description":"The connection event. Explicit-only: sent only to endpoints that list it.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"data":{"type":"object","properties":{"connection":{"$ref":"#/components/schemas/ConnectionWebhookSnapshot"}},"required":["connection"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","data"]},"WebhookTestPayload":{"type":"object","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Payload envelope version. Adding an optional field does not change it; removing or renaming a field would."},"delivery_id":{"type":"string","description":"Unique per event and endpoint, and the same on every retry of that delivery. Dedupe on this."},"event_id":{"type":"string","description":"Shared by every endpoint that receives the same source event. Opaque: do not parse it."},"event_type":{"type":"string","enum":["webhook.test"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event was recorded, not when this attempt was sent."},"app_id":{"type":"string","description":"Your app."},"tenant_id":{"type":"string","description":"The tenant (your customer) the event belongs to. Route on this."},"data":{"type":"object","properties":{"test":{"type":"object","properties":{"endpoint_key":{"type":"string","description":"The webhook's Name the test was sent to: the same value as X-IR-Key-Id."},"requested_by":{"type":"string","enum":["developer"],"x-ir-enum-open":true,"description":"Who asked for the test. Always developer today.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["endpoint_key","requested_by"]}},"required":["test"]}},"required":["schema_version","delivery_id","event_id","event_type","occurred_at","app_id","tenant_id","data"]},"RegisterTenantResponse":{"allOf":[{"$ref":"#/components/schemas/TenantMapping"},{"type":"object","properties":{"created":{"type":"boolean","description":"True only for the request that inserted this mapping; retries return false."},"metadata_matches":{"type":"boolean","description":"Whether the stored name equals the submitted name. Existing metadata always wins and is never updated by registration."}},"required":["created","metadata_matches"]}]},"TenantMapping":{"type":"object","properties":{"tenant_id":{"type":"string"},"external_tenant_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$","description":"Exact, case-sensitive stable customer/workspace organization ID owned by the product backend. Do not reuse an ID for another customer."},"name":{"type":"string"},"status":{"type":"string","description":"Open status string; only active permits registration/consent. Retained inactive mappings remain readable for recovery."}},"required":["tenant_id","external_tenant_id","name","status"]},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type."},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":["string","null"]},"code":{"type":"string"},"request_id":{"type":"string"},"correlation_id":{"type":["string","null"]},"instance":{"type":["string","null"]},"errors":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"},"description":"Per-field breakdown, present when a problem is field-shaped — request-schema validation failures on `/v1` (`400 request.validation_failed`) and `400 accounting.invalid_input` refusals that name the offending field (for example a bulk bind row missing `treatment`). Omitted entirely — never `[]` — otherwise. Capped at 20 entries, so it may not list every failing field."}},"required":["type","title","status","detail","code","request_id","correlation_id","instance"]},"FieldError":{"type":"object","properties":{"field":{"type":"string","description":"The offending field, prefixed with where the value was read from: `body.`, `query.`, `path.`, `header.` or `cookie.` (e.g. `body.tenant_id`). Array elements are indexed (`body.lines[0].amount`). A bare prefix means the whole target was rejected."},"code":{"type":"string","description":"Diagnostic label from the validator's own issue vocabulary (e.g. `invalid_type`, `too_small`). Useful in a log; **not** the stable branch point and not covered by the API stability policy — switch on the top-level `code` instead."},"message":{"type":"string","description":"Human-facing description of what was wrong with this field. May be reworded in any release, and is truncated when long."}},"required":["field","code","message"]},"RegisterTenantRequest":{"type":"object","properties":{"external_tenant_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$","description":"Exact, case-sensitive stable customer/workspace organization ID owned by the product backend. Do not reuse an ID for another customer."},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["external_tenant_id","name"]},"CreateConnectSessionResponse":{"type":"object","properties":{"session_id":{"type":"string","format":"uuid"},"authorize_url":{"type":"string","format":"uri"},"expires_at":{"type":"integer"},"connection_id":{"type":["string","null"]}},"required":["session_id","authorize_url","expires_at","connection_id"]},"CreateConnectSessionRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"provider_key":{"type":"string","enum":["quickbooks","xero","google-meet","microsoft-teams"],"description":"The provider to connect. `xero` uses Xero's fixed scope set: send no `scopes`, or exactly that set. `google-meet` connects a Google account for the Meetings API."},"return_url":{"type":"string","format":"uri"},"scopes":{"type":["array","null"],"items":{"type":"string"}},"state":{"type":["string","null"],"description":"Opaque value echoed back on return."},"actor_user_id":{"type":["string","null"]},"actor_email":{"type":["string","null"],"format":"email"},"local_date":{"type":"string","format":"date","description":"The tenant's local calendar date (YYYY-MM-DD). Seeds the accounting sync start date; the runtime clamps it to UTC yesterday..today. Omitted means UTC yesterday."}},"required":["tenant_id","provider_key","return_url"]},"ConnectionsListResponse":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionPublicDTO"}},"next_cursor":{"type":["string","null"]}},"required":["connections","next_cursor"]},"ConnectionPublicDTO":{"type":"object","properties":{"id":{"type":"string"},"provider_key":{"type":"string"},"provider_account_id":{"type":["string","null"],"description":"The accounting company this connection is bound to: the QuickBooks realm id or the Xero organisation id. Null before the first connect completes and for non-accounting providers."},"provider_account_name":{"type":["string","null"],"description":"Display name of the connected accounting company (QuickBooks CompanyInfo.CompanyName, Xero Organisation.Name), read when the connection was last connected or reconnected. A label only: never use it to identify the company; use `provider_account_id`. Null for non-accounting providers and when no name has been captured for the current company (for example a connection made before this field existed); the next reconnect fills it."},"status":{"type":"string","enum":["connected","reconnect_required","disconnected","disabled"],"x-ir-enum-open":true,"description":"Authoritative runtime lifecycle state for this connection.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"connected_at":{"type":["integer","null"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}},"required":["id","provider_key","provider_account_id","provider_account_name","status","connected_at","created_at","updated_at"]},"DisconnectConnectionRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"provider_key":{"type":"string","enum":["quickbooks","xero","google-meet","microsoft-teams"]},"provider_account_id":{"type":"string","minLength":1},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"required":["tenant_id","provider_key","provider_account_id","idempotency_key"]},"QuickBooksStatusResponse":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"transaction":{"$ref":"#/components/schemas/QuickBooksTransactionStatus"}},"required":["app_id","tenant_id","transaction"]},"QuickBooksMasterRecord":{"type":"object","properties":{"entity_type":{"type":"string","enum":["Customer","Item","TaxCode","TaxRate"],"x-ir-enum-open":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"external_id":{"type":"string","pattern":"^\\d{1,32}$"},"sync_token":{"type":["string","null"]},"active":{"type":"boolean"},"name":{"type":"string"},"provider_updated_at":{"type":["string","null"]},"customer_currency":{"type":["string","null"]},"email":{"type":["string","null"]},"item_type":{"type":["string","null"]},"income_account_id":{"type":["string","null"]},"unit_price_minor":{"type":["integer","null"]},"description":{"type":["string","null"]},"account_type":{"type":["string","null"]},"sales_tax_rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^\\d{1,32}$"},"name":{"type":"string"},"rate_value":{"type":"number"}},"required":["id","name","rate_value"]}},"rate_value":{"type":["number","null"]},"app_id":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"provider_account_id":{"type":"string","pattern":"^\\d{1,32}$"},"observed_at":{"type":"string","format":"date-time"}},"required":["entity_type","external_id","sync_token","active","name","provider_updated_at","customer_currency","email","item_type","income_account_id","unit_price_minor","description","account_type","sales_tax_rates","rate_value","app_id","tenant_id","connection_id","provider_account_id","observed_at"]},"QuickBooksMasterMapping":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"provider_account_id":{"type":"string","pattern":"^\\d{1,32}$"},"erp_id":{"type":"string"},"state":{"type":"string","enum":["active","inactive","drifted","missing","pending"],"x-ir-enum-open":true,"description":"Stable mapping observation state; preserve an unrecognised state without claiming active verification.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"revision":{"type":"integer"},"pending_command_id":{"type":["string","null"]},"record":{"allOf":[{"$ref":"#/components/schemas/QuickBooksMasterRecord"},{"type":["object","null"]}]}},"required":["app_id","tenant_id","connection_id","provider_account_id","erp_id","state","revision","pending_command_id","record"]},"CalendarResourcesListResponse":{"type":"object","properties":{"resources":{"type":"array","items":{"$ref":"#/components/schemas/CalendarResource"}},"next_cursor":{"type":["string","null"]}},"required":["resources","next_cursor"],"additionalProperties":false},"CalendarResource":{"type":"object","properties":{"resource_id":{"type":"string","minLength":1},"grant_id":{"type":"string","minLength":1},"calendar_id":{"type":"string","minLength":1},"status":{"type":"string","enum":["selected","detached"],"x-ir-enum-open":true,"description":"Lifecycle state of this scoped Calendar resource binding.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}},"required":["resource_id","grant_id","calendar_id","status","created_at","updated_at"],"additionalProperties":false},"SelectCalendarResourceRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"discovery_page_id":{"type":"string","minLength":1},"calendar_id":{"type":"string","minLength":1},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"required":["tenant_id","discovery_page_id","calendar_id","idempotency_key"],"additionalProperties":false},"CalendarGrant":{"type":"object","properties":{"grant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1},"provider_key":{"type":"string","enum":["google-calendar"],"x-ir-enum-open":true,"description":"Provider key for this Calendar grant. This implementation emits Google Calendar only.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"principal_id":{"type":"string","minLength":1},"status":{"type":"string","enum":["connected","reconnect_required","disconnected","disabled"],"x-ir-enum-open":true,"description":"Authoritative runtime lifecycle state for this connection.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"capabilities":{"type":"object","properties":{"discover_calendars":{"type":"boolean"},"read_events":{"type":"boolean"}},"required":["discover_calendars","read_events"],"additionalProperties":false},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}},"required":["grant_id","connection_id","provider_key","principal_id","status","capabilities","created_at","updated_at"],"additionalProperties":false},"CalendarRevokeRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"required":["tenant_id","idempotency_key"],"additionalProperties":false},"CalendarDetachRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"required":["tenant_id","idempotency_key"],"additionalProperties":false},"CalendarPublicPage":{"oneOf":[{"type":"object","properties":{"page_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"grant_id":{"type":"string","minLength":1},"next_page_handle":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{43}$"},"created_at":{"type":"integer","minimum":0},"expires_at":{"type":"integer","minimum":0},"resource_id":{"type":"null"},"representation":{"type":"string","enum":["calendar-list"]},"items":{"type":"array","items":{"type":"object","properties":{"identity":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1},"tenantId":{"type":"string","minLength":1},"grantId":{"type":"string","minLength":1},"principalId":{"type":"string","minLength":1},"calendarId":{"type":"string","minLength":1}},"required":["provider","appId","tenantId","grantId","principalId","calendarId"],"additionalProperties":false},"title":{"type":"string"},"timeZone":{"type":"string"},"accessRole":{"type":"string"}},"required":["identity"],"additionalProperties":false},"maxItems":10}},"required":["page_id","grant_id","next_page_handle","created_at","expires_at","resource_id","representation","items"],"additionalProperties":false},{"type":"object","properties":{"page_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"grant_id":{"type":"string","minLength":1},"next_page_handle":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{43}$"},"created_at":{"type":"integer","minimum":0},"expires_at":{"type":"integer","minimum":0},"resource_id":{"type":"string","minLength":1},"representation":{"type":"string","enum":["series-and-exceptions"]},"items":{"type":"array","items":{"type":"object","properties":{"identity":{"type":"object","properties":{"provider":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1},"tenantId":{"type":"string","minLength":1},"grantId":{"type":"string","minLength":1},"principalId":{"type":"string","minLength":1},"calendarId":{"type":"string","minLength":1},"eventId":{"type":"string","minLength":1}},"required":["provider","appId","tenantId","grantId","principalId","calendarId","eventId"],"additionalProperties":false},"status":{"type":"string","enum":["confirmed","tentative","cancelled"],"x-ir-enum-open":true,"description":"Provider event lifecycle status.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"title":{"type":"string"},"start":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["date"]},"date":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["instant"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["zoned-date-time"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime","timeZone"],"additionalProperties":false}]},"end":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["date"]},"date":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["instant"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["zoned-date-time"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime","timeZone"],"additionalProperties":false}]},"endTimeUnspecified":{"type":"boolean"},"recurrence":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["single"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["series"]},"rules":{"type":"array","items":{"type":"string"}}},"required":["kind","rules"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["exception"]},"seriesId":{"type":"string","minLength":1},"originalStart":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["date"]},"date":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["instant"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["zoned-date-time"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime","timeZone"],"additionalProperties":false}]}},"required":["kind","seriesId","originalStart"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["occurrence"]},"seriesId":{"type":"string","minLength":1},"originalStart":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["date"]},"date":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","date"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["instant"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["zoned-date-time"]},"dateTime":{"type":"string","minLength":1},"timeZone":{"type":"string","minLength":1}},"required":["kind","dateTime","timeZone"],"additionalProperties":false}]}},"required":["kind","seriesId","originalStart"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["unknown"]}},"required":["kind"],"additionalProperties":false}]}},"required":["identity","status","recurrence"],"additionalProperties":false},"maxItems":10}},"required":["page_id","grant_id","next_page_handle","created_at","expires_at","resource_id","representation","items"],"additionalProperties":false}]},"MappingDryRunResult":{"type":"object","properties":{"ok":{"type":"boolean"},"provider_payload":{"type":"object","additionalProperties":{}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/MappingWarning"}},"mapping_source":{"type":"string","enum":["active","request_override","none"],"x-ir-enum-open":true,"description":"`active` = used field_mappings row; `request_override` = used mapping_rules from body; `none` = no rules available, provider_payload is empty.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["ok","provider_payload","warnings","mapping_source"]},"MappingWarning":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string","enum":["mapping.required_field_missing","mapping.transform_unknown","mapping.type_mismatch","quickbooks.required_key_missing"],"x-ir-enum-open":true,"description":"Machine-readable warning code. Switch on this, never on `message`.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"message":{"type":"string"},"transform":{"type":"string","description":"Set only on `mapping.transform_unknown` warnings — the offending transform name. Operators can read this to fix the rule without parsing `message`."}},"required":["path","code","message"]},"MappingDryRunRequest":{"type":"object","properties":{"sample_payload":{"type":"object","additionalProperties":{},"description":"Tenant-supplied sample to run through the active (or supplied) mapping rules."},"mapping_rules":{"type":"array","items":{"$ref":"#/components/schemas/MappingRule"},"description":"Optional override; when present, these rules are used instead of the sync_profile's active mapping. Useful for previewing an unpublished draft."}},"required":["sample_payload"]},"MappingRule":{"type":"object","properties":{"source":{"type":"string","minLength":1,"example":"invoice.customer.email"},"target":{"type":"string","minLength":1,"example":"BillEmail.Address"},"transform":{"type":["string","null"],"description":"Optional transform; v1 supports 'lowercase' and 'trim'. Unknown transforms emit a warning and pass the value through untransformed."},"warn_if_source_missing":{"type":"boolean","description":"When true and the source resolves to null/undefined, the dry-run emits a `mapping.required_field_missing` warning. Renamed from `required` (breaking): this flag is dry-run feedback only and is distinct from whether the provider requires the target field (a publish-time check)."}},"required":["source","target"]},"OperationsExecuteResult":{"type":"object","properties":{"job_id":{"type":"string"},"correlation_id":{"type":["string","null"]},"status":{"type":"string","enum":["queued"],"x-ir-enum-open":true,"description":"Acknowledgement state. The job is enqueued.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"polling_url":{"type":"string","description":"Relative path for polling this job, resolved against your runtime base URL. Self-contained and directly followable: it already carries the `tenant_id` query parameter that `GET /v1/sync-jobs/{id}` requires. Use it verbatim — the HMAC canonical string covers path **and** query, so re-deriving or re-ordering it breaks the signature. Poll it for progress.","example":"/v1/sync-jobs/01J0000000000000000000000?tenant_id=tenant_test_001"}},"required":["job_id","correlation_id","status","polling_url"]},"OperationsExecuteRequest":{"type":"object","properties":{"interactive":{"type":"boolean","default":false,"description":"Invoice-only scheduling preference: true requires a QuickBooks Invoice-create recipe. The first accepted job retains it. Both lanes share provider quota and Invoice serialization."},"tenant_id":{"type":"string","minLength":1},"provider_key":{"type":"string","minLength":1,"description":"Must match the deployed recipe's provider."},"connection_id":{"type":"string","minLength":1},"recipe_key":{"type":"string","minLength":1,"description":"Deployed recipe key to admit."},"recipe_version":{"type":"integer","exclusiveMinimum":0,"description":"Deployed recipe version to admit."},"trigger_type":{"type":"string","minLength":1},"object_type":{"type":"string","minLength":1,"description":"Must match the deployed recipe's object type."},"internal_object_id":{"type":"string","minLength":1},"idempotency_key":{"type":"string","minLength":1},"mapping_version":{"type":"integer","exclusiveMinimum":0},"payload":{"description":"Recipe-specific input. Google Calendar clients must use the published CalendarDiscoveryInitialPayload, CalendarDiscoveryResumePayload, CalendarEventsInitialPayload, or CalendarEventsResumePayload component matching the selected recipe and traversal mode."},"correlation_id":{"type":"string"},"request_id":{"type":"string"}},"required":["tenant_id","provider_key","connection_id","recipe_key","recipe_version","trigger_type","object_type","internal_object_id","payload"]},"AccountingProviders":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"provider_key":{"type":"string"},"display_name":{"type":"string"},"enabled":{"type":"boolean"},"capabilities":{"type":"object","properties":{"operations":{"type":"array","items":{"type":"string"}},"currencies":{"type":"array","items":{"type":"string"}},"historical_sync":{"type":"boolean"},"multi_invoice_payment":{"type":"boolean"},"limits":{"type":"array","items":{"type":"string"}}},"required":["operations","currencies","historical_sync","multi_invoice_payment","limits"]},"mapping_kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"granularity":{"type":"string","enum":["record","code"],"x-ir-enum-open":true,"description":"How the ERP binds this kind.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"required_for":{"type":"array","items":{"type":"string"}}},"required":["kind","label","granularity","required_for"]}}},"required":["provider_key","display_name","enabled","capabilities","mapping_kinds"]}},"connection":{"type":["object","null"],"properties":{"connection_id":{"type":"string"},"provider_key":{"type":"string"},"provider_account_id":{"type":"string"},"provider_account_name":{"type":["string","null"],"description":"Display name of the connected accounting company (QuickBooks CompanyInfo.CompanyName, Xero Organisation.Name), read when the connection was last connected or reconnected. A label only: never use it to identify the company; use `provider_account_id`. Null for non-accounting providers and when no name has been captured for the current company (for example a connection made before this field existed); the next reconnect fills it."}},"required":["connection_id","provider_key","provider_account_id","provider_account_name"]},"connection_state":{"type":"string","enum":["connected","none","multiple"],"x-ir-enum-open":true,"description":"Whether the tenant has exactly one active accounting connection.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["providers","connection","connection_state"]},"AccountingReference":{"type":"object","properties":{"kind":{"type":"string"},"provider_ref":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"rate_percent":{"type":"string"},"email":{"type":["string","null"]},"account_type":{"type":["string","null"]},"account_code":{"type":["string","null"]},"recommended":{"type":"boolean"},"usable":{"type":"boolean","description":"Read live: whether a bind can use the record now. Absent where unknown (snapshot rows, or a QuickBooks tax code whose rates could not be read); a live match never `matched` a record of unknown usability."},"unusable_reason":{"type":["string","null"],"enum":["inactive","not_usable_for_kind",null],"x-ir-enum-open":true,"description":"Why a listed record cannot be used now: inactive (archived in the provider), or not_usable_for_kind (e.g. a QuickBooks Category item). Treat an unknown reason as not usable.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["kind","provider_ref","name","active"]},"AccountingReferenceOptionPage":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"provider_ref":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"email":{"type":["string","null"]},"account_type":{"type":["string","null"],"description":"Accounts: the provider's account type, as it names it."},"account_code":{"type":["string","null"],"description":"Accounts: the provider's account code or number, when set."},"recommended":{"type":"boolean","description":"The usual pick for the kind. Advice only."},"usable":{"type":"boolean","description":"Read live: whether a bind can use the record now. Absent where unknown (snapshot rows, or a QuickBooks tax code whose rates could not be read); a live match never `matched` a record of unknown usability."},"unusable_reason":{"type":["string","null"],"enum":["inactive","not_usable_for_kind",null],"x-ir-enum-open":true,"description":"Why a listed record cannot be used now: inactive (archived in the provider), or not_usable_for_kind (e.g. a QuickBooks Category item). Treat an unknown reason as not usable.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["kind","provider_ref","name","active"]}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]},"AccountingMapping":{"type":"object","properties":{"connection_id":{"type":"string"},"kind":{"type":"string"},"erp_code":{"type":"string"},"provider_ref":{"type":["string","null"]},"provider_name":{"type":["string","null"]},"treatment":{"type":["string","null"]},"state":{"type":"string","enum":["active","inactive","drifted","missing","pending","incomplete"],"x-ir-enum-open":true,"description":"Mapping state; treat an unknown state as not usable.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"revision":{"type":"integer"}},"required":["connection_id","kind","erp_code","provider_ref","provider_name","treatment","state","revision"]},"AccountingSettings":{"type":"object","properties":{"connection_id":{"type":"string"},"provider_key":{"type":"string"},"provider_account_id":{"type":"string"},"sync_start_date":{"type":"string","description":"New documents created before this day are refused with accounting.before_sync_start: a create is judged by its erp_created_at when sent, else by its document date. Writes to documents already linked on the connection are not checked against it. Set at connect; the ERP may move it with PUT. Before moving it earlier, match or link the provider's existing records of that period so they are not written twice."},"record_types":{"type":"array","items":{"type":"string","enum":["invoice","payment","credit_memo","refund"],"x-ir-enum-open":true,"description":"Neutral record type a connection can sync; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."}},"historical_sync":{"type":"boolean","description":"False in v1: no documents before sync_start_date."},"revision":{"type":"integer","description":"Send as expected_revision on the next PUT."}},"required":["connection_id","provider_key","provider_account_id","sync_start_date","record_types","historical_sync","revision"]},"AccountingConnectionCapabilities":{"type":"object","properties":{"connection_id":{"type":"string"},"provider_key":{"type":"string"},"provider_account_id":{"type":"string"},"operations":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["provider_unsupported","not_offered_yet","not_enabled_for_app","disabled","disabled_for_tenant","disabled_for_connection","misconfigured","reconnect_required","unavailable",null],"x-ir-enum-open":true,"description":"Why it is not available: provider_unsupported (the provider has no such operation or behaviour; see alternative), not_offered_yet (the runtime does not offer it yet), not_enabled_for_app, disabled (off for every tenant), disabled_for_tenant (this tenant's Kill or Disarm), disabled_for_connection (the connection's settings turn the record type off, or an exact per-connection case is not granted), misconfigured (ask support; retrying does not help), reconnect_required (the connection was consented before the operation needed a scope it now needs; reconnect it, then read again), unavailable (could not be determined; read again later). Treat an unknown reason as not available.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"alternative":{"type":["string","null"],"description":"A neutral operation to use instead when the provider has none."},"detail":{"type":["string","null"],"description":"Human-readable; free text that may change. Switch on reason, never on this."},"performed_as":{"type":["string","null"],"description":"The neutral operation the provider actually performs, when it differs (Xero: accounting.payment.void deletes the payment; the result status is deleted). Null when performed as named."},"side_effects":{"type":"array","items":{"type":"string","enum":["applied_payments_left_unapplied","excess_left_unapplied","credit_note_created"],"x-ir-enum-open":true,"description":"An effect on another document: applied_payments_left_unapplied (a payment applied to the invoice stays in the provider, unapplied), excess_left_unapplied (what the invoice cannot take stays unapplied as customer credit), credit_note_created (the provider records a refund as a credit note plus a cash refund).\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}}},"required":["operation","available","reason","alternative","detail","performed_as","side_effects"]}},"features":{"type":"array","items":{"type":"object","properties":{"feature":{"type":"string","enum":["invoice.reference","invoice.update_lines","invoice.update_amounts_when_paid","invoice.lower_below_paid","payment.multi_invoice","payment.deposit_account_optional","payment.payment_method_optional","refund.payment_method_optional","prepayment.auto_apply_credit"],"x-ir-enum-open":true,"description":"A provider-neutral behaviour; new features may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"supported":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["provider_unsupported","not_offered_yet","not_enabled_for_app","disabled","disabled_for_tenant","disabled_for_connection","misconfigured","reconnect_required","unavailable",null],"x-ir-enum-open":true,"description":"Why it is not available: provider_unsupported (the provider has no such operation or behaviour; see alternative), not_offered_yet (the runtime does not offer it yet), not_enabled_for_app, disabled (off for every tenant), disabled_for_tenant (this tenant's Kill or Disarm), disabled_for_connection (the connection's settings turn the record type off, or an exact per-connection case is not granted), misconfigured (ask support; retrying does not help), reconnect_required (the connection was consented before the operation needed a scope it now needs; reconnect it, then read again), unavailable (could not be determined; read again later). Treat an unknown reason as not available.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"alternative":{"type":["string","null"]},"detail":{"type":["string","null"]}},"required":["feature","supported","reason","alternative","detail"]}}},"required":["connection_id","provider_key","provider_account_id","operations","features"]},"AccountingRecordPage":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/AccountingRecord"}},"next_cursor":{"type":["string","null"]},"source":{"type":"string","enum":["snapshot","live"],"x-ir-enum-open":true,"description":"Where the records were read; new sources may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"as_of":{"type":["string","null"],"description":"When the snapshot pull started; null for live."}},"required":["records","next_cursor"]},"AccountingRecord":{"type":"object","properties":{"provider_ref":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"email":{"type":["string","null"]},"sku":{"type":["string","null"]},"rate_percent":{"type":["string","null"],"description":"Tax codes: the effective sales rate, e.g. `13` or `14.975` (on QuickBooks, the sum of the code's sales rates); null when a rate cannot be read."},"usable":{"type":"boolean","description":"Read live: whether a bind can use the record now. Absent where unknown (snapshot rows, or a QuickBooks tax code whose rates could not be read); a live match never `matched` a record of unknown usability."},"unusable_reason":{"type":["string","null"],"enum":["inactive","not_usable_for_kind","pending_change","currency_unknown",null],"x-ir-enum-open":true,"description":"Why a listed record cannot be used now: inactive (archived in the provider), not_usable_for_kind (e.g. a QuickBooks Category item), pending_change (prepayments: a payment or prepayment write on this connection may hold the credit and is not settled yet; retry later), or currency_unknown (prepayments: the provider reported no currency for the credit, so it cannot be bound). Treat an unknown reason as not usable.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"suggested_treatment":{"type":["string","null"],"enum":["taxable","zero_rated","exempt","not_applicable",null],"x-ir-enum-open":true,"description":"Tax codes: the ERP treatment the provider code suggests (`taxable` above 0; `exempt` or `zero_rated` at 0 when the provider marks it), or null. A hint only; a bind takes the treatment you send.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"tax_number":{"type":["string","null"],"description":"Customers, live reads on providers that have one (Xero TaxNumber): the tax or business number. Absent when empty."},"account_number":{"type":["string","null"],"description":"Customers, live reads on providers that have one (Xero AccountNumber). Absent when empty."},"credit_type":{"type":"string","enum":["payment","overpayment"],"x-ir-enum-open":true,"description":"Prepayments: the provider's kind of credit (QuickBooks payment, Xero overpayment); new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"customer_provider_ref":{"type":"string","description":"Prepayments: the provider customer (QuickBooks Customer, Xero contact) of the credit."},"currency":{"type":["string","null"],"description":"Prepayments: the credit's currency; null when the provider reported none (such a credit is not usable: currency_unknown)."},"date":{"type":["string","null"],"description":"Prepayments: the credit's date (YYYY-MM-DD)."},"reference":{"type":["string","null"],"description":"Prepayments: the provider's reference on the credit, when set."},"total_amount":{"type":"string","description":"Prepayments: the amount the customer paid, as a decimal string."},"open_amount":{"type":"string","description":"Prepayments: the credit not yet applied or refunded (QuickBooks UnappliedAmt, Xero RemainingCredit). Only credits above 0 are listed."},"bound_erp_id":{"type":["string","null"],"description":"Prepayments: the ERP prepayment id that holds the credit now (bound, or created by accounting.prepayment.create); null when free."}},"required":["provider_ref","name","active"]},"AccountingRecordMatch":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string"},"status":{"type":"string","enum":["matched","suggested","none"],"x-ir-enum-open":true,"description":"Treat an unknown status as needing review.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"provider_ref":{"type":["string","null"]},"matched_on":{"type":["string","null"],"enum":["email","sku","name",null],"x-ir-enum-open":true,"description":"Key the record matched on; new keys may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"candidates":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AccountingRecord"},{"type":"object","properties":{"bound_erp_id":{"type":["string","null"]},"match_reasons":{"type":"array","items":{"type":"string","enum":["email","sku","name","loose_name","tax_number","account_number","rate","customer","amount"],"x-ir-enum-open":true,"description":"Why a candidate was offered; new reasons may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"The keys this candidate equals (email, sku, name, tax_number, account_number), loose_name when its name equals only once punctuation and spacing are ignored, or rate for a tax code offered by its rate. Only email, sku and name can make a record `matched`."}},"required":["bound_erp_id","match_reasons"]}]}},"not_matched_reason":{"type":["string","null"],"enum":["shared_with_other_record","ambiguous","bound_to_other_record","inactive","not_usable_for_kind",null],"x-ir-enum-open":true,"description":"Why a record with a key hit is not `matched`: shared_with_other_record (another record of this request matched the same provider record), ambiguous (several provider records equal the key), bound_to_other_record, inactive, not_usable_for_kind. Null when nothing decides, including when the record's usability could not be read (`usable` absent). Treat an unknown reason as needing review.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"unsearchable_keys":{"type":"array","items":{"type":"string","enum":["email","sku","name","tax_number","account_number"],"x-ir-enum-open":true,"description":"A match key; new keys may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Keys this record has a value for that the provider cannot search, e.g. a Xero name or email containing a double quote or backslash, a SKU over Xero's 30-character item code, or a value with a control character. Those keys found nothing; search with GET .../records/{entity}?q=. Absent when none."},"candidates_truncated":{"type":"boolean","description":"Snapshot matches only: this record's primary key or name is shared by more snapshot records than a match returns per key (20), so candidates holds at most that many; never matched on a cut primary key. Search with GET .../records/{entity}?q= to see them all. Absent otherwise."}},"required":["erp_id","status","provider_ref","matched_on","candidates","not_matched_reason"]}},"unsupported_keys":{"type":"array","items":{"type":"string","enum":["email","sku","name","tax_number","account_number"],"x-ir-enum-open":true,"description":"A key this source could not compare; new keys may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Keys this source could not compare: the provider refused to filter by them (those records matched on the other keys), or it has no such field (tax_number and account_number on QuickBooks, tax_number on a live Xero match). Listed only when a record sent a value."},"source":{"type":"string","enum":["snapshot","live"],"x-ir-enum-open":true,"description":"Where the records were read; new sources may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"as_of":{"type":["string","null"],"description":"When the snapshot pull started; null for live."},"snapshot_id":{"type":["string","null"]}},"required":["results","unsupported_keys","source","as_of","snapshot_id"]},"AccountingRecordBind":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string"},"status":{"type":"string","enum":["bound","refused","rate_limited","not_attempted"],"x-ir-enum-open":true,"description":"Per-row bind outcome; retry rate_limited and not_attempted rows.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"code":{"type":["string","null"]},"retry_after":{"type":["integer","null"]},"bound_provider_ref":{"type":"string","description":"With reason record_already_bound: the provider record the ERP id is bound to. No bind returns it any more: a bind re-binds an ERP id already bound to a different record, on every provider."},"reason":{"type":"string","enum":["bound_to_other_record","record_already_bound","not_usable_for_kind","inactive","ambiguous","pending_change","connection_changed","customer_mismatch","no_open_credit","has_applications","create_failed","currency_unknown"],"x-ir-enum-open":true,"description":"On a refused row, why it was refused, the same on every provider; absent or null when not known: bound_to_other_record (bound_erp_id holds it), record_already_bound (bound_provider_ref), not_usable_for_kind, inactive, ambiguous, pending_change, connection_changed. Prepayments also: customer_mismatch (the credit belongs to another customer), no_open_credit (nothing left to apply), has_applications (a re-bind of a prepayment the runtime has applied), create_failed (this ERP id's own accounting.prepayment.create failed; bind the credit under a new erp_id), currency_unknown (the provider reported no currency for the credit). Treat an unknown reason as pick another record.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"bound_erp_id":{"type":"string","description":"Only with reason `bound_to_other_record`: the ERP id that holds the provider record now."},"mapping":{"type":["object","null"],"properties":{"provider_ref":{"type":["string","null"]},"provider_name":{"type":["string","null"]},"state":{"type":"string"},"revision":{"type":"integer","description":"The mapping's revision. On a prepayment row, the binding's version stamp: it changes on every re-bind; compare it for equality only."}},"required":["provider_ref","provider_name","state","revision"]},"prepayment":{"type":"object","properties":{"provider_ref":{"type":"string"},"origin":{"type":"string","enum":["bound","runtime"],"x-ir-enum-open":true,"description":"bound: a credit entered in the provider and linked by a bind (the runtime did not create it). runtime: created by accounting.prepayment.create.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"change":{"type":"string","enum":["linked","rebound","unchanged"],"x-ir-enum-open":true,"description":"What this row did; new values may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"previous_provider_ref":{"type":["string","null"],"description":"With change rebound: the credit the ERP id was bound to before."},"credit_type":{"type":"string","enum":["payment","overpayment"],"x-ir-enum-open":true,"description":"Prepayments: the provider's kind of credit (QuickBooks payment, Xero overpayment); new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"customer_provider_ref":{"type":"string"},"currency":{"type":["string","null"]},"date":{"type":["string","null"]},"total_amount":{"type":"string"},"open_amount":{"type":"string"}},"required":["provider_ref","origin","change","previous_provider_ref","credit_type","customer_provider_ref","currency","date","total_amount","open_amount"],"description":"Prepayment rows that bound: the credit as the provider holds it now."}},"required":["erp_id","status","code","retry_after","mapping"]}}},"required":["results"]},"AccountingRecordSnapshot":{"type":"object","properties":{"snapshot_id":{"type":"string"},"entity":{"type":"string","enum":["customer","item"],"x-ir-enum-open":true,"description":"Record type to snapshot; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"status":{"type":"string","enum":["pending","running","ready","failed","expired"],"x-ir-enum-open":true,"description":"Treat an unknown status as not ready.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"job_id":{"type":["string","null"],"description":"The background sync job filling this snapshot."},"record_count":{"type":"integer"},"provider_calls":{"type":"integer"},"waiting_on":{"type":["string","null"],"enum":["duty_cycle","slot","daily_budget",null],"x-ir-enum-open":true,"description":"Set while a running snapshot waits before its next page: why it is paused. New reasons may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"as_of":{"type":["string","null"],"description":"ISO 8601. When the pull started; records changed after this may be missing."},"expires_at":{"type":["string","null"],"description":"ISO 8601. The snapshot's rows are deleted after this."},"created_at":{"type":"string"},"error_code":{"type":["string","null"]}},"required":["snapshot_id","entity","status","job_id","record_count","provider_calls","waiting_on","as_of","expires_at","created_at","error_code"]},"AccountingBindJob":{"type":"object","properties":{"job_id":{"type":"string","description":"The background sync job; its webhooks carry this id."},"entity":{"type":"string","enum":["customer","item"],"x-ir-enum-open":true,"description":"Record type to bind; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"status":{"type":"string","enum":["pending","running","completed","failed"],"x-ir-enum-open":true,"description":"Treat an unknown status as still running.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"row_count":{"type":"integer"},"bound_count":{"type":"integer"},"refused_count":{"type":"integer"},"not_attempted_count":{"type":"integer"},"provider_calls":{"type":"integer"},"waiting_on":{"type":["string","null"],"enum":["duty_cycle","slot","daily_budget",null],"x-ir-enum-open":true,"description":"Set while a running job waits before its next batch: why it is paused. New reasons may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"error_code":{"type":["string","null"]},"created_at":{"type":"string"},"ended_at":{"type":["string","null"]}},"required":["job_id","entity","status","row_count","bound_count","refused_count","not_attempted_count","provider_calls","waiting_on","error_code","created_at","ended_at"]},"AccountingBindJobResults":{"allOf":[{"$ref":"#/components/schemas/AccountingBindJob"},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string"},"provider_ref":{"type":"string"},"status":{"type":"string","enum":["bound","refused","not_attempted"],"x-ir-enum-open":true,"description":"Per-row outcome. not_attempted rows were never tried: send them again in a new job.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"code":{"type":["string","null"],"description":"On a refused row: accounting.reference_not_found, accounting.mapping_conflict or accounting.provider_unavailable, as the bind route answers them."},"bound_provider_ref":{"type":["string","null"],"description":"With reason record_already_bound: the provider record the ERP id is bound to. No bind returns it any more: a bind re-binds an ERP id already bound to a different record, on every provider."},"reason":{"type":["string","null"],"enum":["bound_to_other_record","record_already_bound","not_usable_for_kind","inactive","ambiguous","pending_change","connection_changed",null],"x-ir-enum-open":true,"description":"On a refused row, why it was refused, the same on every provider; absent or null when not known: bound_to_other_record (bound_erp_id holds it), record_already_bound (bound_provider_ref), not_usable_for_kind, inactive, ambiguous, pending_change, connection_changed. Treat an unknown reason as pick another record.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"bound_erp_id":{"type":["string","null"],"description":"Only with reason `bound_to_other_record`: the ERP id that holds the provider record."}},"required":["erp_id","provider_ref","status","code","bound_provider_ref","reason","bound_erp_id"]}},"next_cursor":{"type":["string","null"]}},"required":["results","next_cursor"]}]},"AccountingDocumentState":{"type":"object","properties":{"provider_key":{"type":"string"},"document_type":{"type":"string","enum":["invoice","payment","prepayment"],"x-ir-enum-open":true,"description":"Neutral document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"erp_id":{"type":"string"},"provider_id":{"type":"string"},"revision":{"type":["string","null"],"description":"Opaque. Send it as expected_revision on the next write. Null only for a deleted document."},"provider_account_id":{"type":"string"},"status":{"type":"string","description":"Provider status, e.g. open, partially_paid, paid, voided, deleted; treat an unknown value as not writable."},"currency":{"type":["string","null"]},"total_amount":{"type":["string","null"]},"balance":{"type":["string","null"],"description":"Open balance; for a prepayment, the credit not yet applied to an invoice; null for a payment."},"net_amount":{"type":["string","null"],"description":"Invoice only: net amount (before tax) from this read."},"total_tax":{"type":["string","null"],"description":"Invoice only: total tax from this read."},"tax_lines":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AccountingResultTaxLine"},"description":"Invoice only: the per-rate tax from this read, under this connection's tax code mappings, in the before.totals.tax_lines shape. Null when a provider tax rate has no current tax code mapping or the provider's tax rates could not be read."},"provider_updated_at":{"type":"string"},"observed_at":{"type":"string"}},"required":["provider_key","document_type","erp_id","provider_id","revision","provider_account_id","status","currency","total_amount","balance","provider_updated_at","observed_at"]},"AccountingResultTaxLine":{"type":"object","properties":{"tax_code":{"type":"string","description":"The ERP tax code."},"component":{"type":"string","description":"The provider rate name within the tax code (QuickBooks TaxRate, Xero component)."},"rate_percent":{"type":"string"},"taxable_amount":{"type":"string"},"tax_amount":{"type":"string"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"]},"AccountingDocumentLink":{"type":"object","properties":{"provider_key":{"type":"string"},"document_type":{"type":"string","enum":["invoice"],"x-ir-enum-open":true,"description":"Neutral document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"erp_id":{"type":"string"},"provider_id":{"type":"string"},"provider_account_id":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string"},"provider_line_id":{"type":"string"}},"required":["erp_line_id","provider_line_id"]}},"outcome":{"type":"string","enum":["recorded","unchanged"],"x-ir-enum-open":true,"description":"recorded: written now; unchanged: the same link already existed.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["provider_key","document_type","erp_id","provider_id","provider_account_id","lines","outcome"]},"AccountingDocumentLinkRequest":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"provider_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the provider invoice the runtime created."},"lines":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"provider_line_id":{"type":"string","pattern":"^(\\d{1,32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"required":["erp_line_id","provider_line_id"],"additionalProperties":false,"description":"The provider line id the ERP kept from the old result."},{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"item":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"tax_code":{"type":"string","minLength":1,"maxLength":128},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"quantity":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,6})?$"},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,6})?$"},"description":{"type":"string","maxLength":4000}},"required":["erp_line_id","item","tax_code","amount"],"additionalProperties":false,"description":"The line exactly as it was created; it must match exactly one verified provider line."}]},"minItems":1,"maxItems":100}},"required":["tenant_id","lines"],"additionalProperties":false},"AccountingInvoiceOnlineLink":{"type":"object","properties":{"provider_key":{"type":"string"},"erp_id":{"type":"string"},"provider_id":{"type":"string"},"url":{"type":["string","null"],"description":"The customer's online view and payment page for this invoice, as the provider issues it. Null when the provider has none for it now, e.g. QuickBooks online payments are off or the invoice has no customer email, or a Xero invoice is not yet approved."}},"required":["provider_key","erp_id","provider_id","url"]},"AccountingOperationAccepted":{"type":"object","properties":{"job_id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string","enum":["queued"]},"idempotent_replay":{"type":"boolean"},"polling_url":{"type":"string"}},"required":["job_id","operation","status","idempotent_replay","polling_url"]},"AccountingOperationConflict":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"reason":{"type":"string","description":"Why, when the runtime can say. mapping_changed (with accounting.document_unlinked): the ERP prepayment of an accounting.prepayment.apply was re-bound to another credit after the request was accepted; its job was cancelled before it was queued and nothing was sent. Resend under a new idempotency_key. Treat an unknown reason as refused."},"job_id":{"type":"string","description":"With reason mapping_changed: the cancelled job, readable at polling_url."},"polling_url":{"type":"string","description":"With job_id: GET it for the job's state (cancelled, error.reason mapping_changed)."}}}]},"AccountingOperationRequest":{"oneOf":[{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP record id. For documents created through quickbooks(), reuse the old internal_object_id."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.customer.upsert"]},"payload":{"$ref":"#/components/schemas/AccountingCustomerUpsertPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP record id. For documents created through quickbooks(), reuse the old internal_object_id."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.item.upsert"]},"payload":{"$ref":"#/components/schemas/AccountingItemUpsertPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP record id. For documents created through quickbooks(), reuse the old internal_object_id."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.invoice.create"]},"payload":{"$ref":"#/components/schemas/AccountingInvoiceCreatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The invoice's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.invoice.void"]},"payload":{"$ref":"#/components/schemas/AccountingInvoiceVoidPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The invoice's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.invoice.update"]},"payload":{"$ref":"#/components/schemas/AccountingInvoiceUpdatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of the payment."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.payment.create"]},"payload":{"$ref":"#/components/schemas/AccountingPaymentCreatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$","description":"Stable ERP id of the refund."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.refund.create"]},"payload":{"$ref":"#/components/schemas/AccountingRefundCreatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$","description":"Stable ERP id of the credit memo."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.credit_memo.create"]},"payload":{"$ref":"#/components/schemas/AccountingCreditMemoCreatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this credit application; retries reuse it."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.credit_memo.apply"]},"payload":{"$ref":"#/components/schemas/AccountingCreditMemoApplyPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The payment's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.payment.void"]},"payload":{"$ref":"#/components/schemas/AccountingPaymentVoidPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The payment's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.payment.delete"]},"payload":{"$ref":"#/components/schemas/AccountingPaymentDeletePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The payment's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.payment.update"]},"payload":{"$ref":"#/components/schemas/AccountingPaymentUpdatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The invoice's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.invoice.delete"]},"payload":{"$ref":"#/components/schemas/AccountingInvoiceDeletePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of the prepayment (wallet top-up)."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.prepayment.create"]},"payload":{"$ref":"#/components/schemas/AccountingPrepaymentCreatePayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this application; retries reuse it."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.prepayment.apply"]},"payload":{"$ref":"#/components/schemas/AccountingPrepaymentApplyPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The application's stable ERP id, as sent to accounting.prepayment.apply."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.prepayment.unapply"]},"payload":{"$ref":"#/components/schemas/AccountingPrepaymentUnapplyPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of the refund."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"erp_created_at":{"type":"string","format":"date-time","description":"Optional. When the ERP created this document, RFC 3339 with the tenant's local UTC offset (e.g. 2026-11-18T09:12:00-05:00). When sent, the sync start date is compared with this timestamp's calendar date instead of the document date, so a document created after the connection but dated earlier is admitted. Not part of the request identity."},"operation":{"type":"string","enum":["accounting.prepayment.refund"]},"payload":{"$ref":"#/components/schemas/AccountingPrepaymentRefundPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"Optional; when sent it must be the tenant's active accounting connection."},"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The prepayment's stable ERP id, as sent when it was created."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"operation":{"type":"string","enum":["accounting.prepayment.void"]},"payload":{"$ref":"#/components/schemas/AccountingPrepaymentVoidPayload"}},"required":["tenant_id","erp_id","idempotency_key","operation","payload"],"additionalProperties":false}]},"AccountingCustomerUpsertPayload":{"type":"object","properties":{"customer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":254,"format":"email"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"phone":{"type":"string","minLength":1,"maxLength":30},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Contact person's given name."},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Contact person's family name."},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"QuickBooks only (CompanyName); Xero's contact name is `name`."},"billing_address":{"$ref":"#/components/schemas/AccountingAddress"},"shipping_address":{"$ref":"#/components/schemas/AccountingAddress"}},"required":["name","currency"],"additionalProperties":false,"description":"Fields left out are kept as the provider has them on an update; an address sent replaces the stored one (its omitted parts are cleared). Contact fields other than name, email and currency are written but not read back."}},"required":["customer"],"additionalProperties":false},"AccountingAddress":{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":500},"line2":{"type":"string","minLength":1,"maxLength":500},"city":{"type":"string","minLength":1,"maxLength":255},"region":{"type":"string","minLength":1,"maxLength":255,"description":"Province or state, e.g. ON."},"postal_code":{"type":"string","minLength":1,"maxLength":30},"country":{"type":"string","minLength":1,"maxLength":50}},"required":["line1"],"additionalProperties":false,"description":"Printed on invoices."},"AccountingItemUpsertPayload":{"type":"object","properties":{"item":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["service","non_inventory"],"description":"QuickBooks Service or NonInventory. Xero has one untracked item kind for both. Inventory (tracked) items are not created here."},"income_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as income_account."},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"description":{"type":"string","maxLength":1000},"sku":{"type":"string","minLength":1,"maxLength":100,"description":"QuickBooks only (Sku); Xero's item code is fixed."}},"required":["name","type","income_account","unit_price"],"additionalProperties":false}},"required":["item"],"additionalProperties":false},"AccountingInvoiceCreatePayload":{"type":"object","properties":{"invoice":{"type":"object","properties":{"number":{"type":"string","minLength":1,"maxLength":21},"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"reference":{"type":"string","maxLength":255,"description":"Printed on the invoice (Xero Reference, QuickBooks CustomerMemo). Cleaned before use: line breaks and tabs become one space, other control characters are removed, surrounding spaces are trimmed; empty after cleaning means no reference. Refused with accounting.operation_disabled until the provider's invoice reference capability is enabled."},"private_note":{"type":"string","maxLength":4000,"description":"Internal note; not shown to the customer."},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"item":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"description":{"type":"string","maxLength":4000},"quantity":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,6})?$"},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_code":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_line_id","item","amount","tax_code"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["issue_date","currency","customer","lines"],"additionalProperties":false},"expected_totals":{"type":"object","properties":{"net_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_tax":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string","minLength":1,"maxLength":128},"component":{"type":"string","minLength":1,"maxLength":100,"description":"Provider rate name within the tax code."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$"},"taxable_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["net_amount","total_tax","total_amount"],"additionalProperties":false}},"required":["invoice","expected_totals"],"additionalProperties":false},"AccountingInvoiceVoidPayload":{"type":"object","properties":{"void_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this void; retries reuse it."},"invoice":{"type":"object","properties":{"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The invoice's own date, checked against the closing date."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."},"before_totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["issue_date","currency","customer","expected_revision","before_totals"],"additionalProperties":false}},"required":["void_id","invoice"],"additionalProperties":false},"AccountingBeforeTotals":{"type":"object","properties":{"net_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_tax":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string","minLength":1,"maxLength":128},"component":{"type":"string","minLength":1,"maxLength":100,"description":"Provider rate name within the tax code."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$"},"taxable_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"],"additionalProperties":false},"maxItems":50}},"required":["net_amount","total_tax","total_amount","tax_lines"],"additionalProperties":false},"AccountingInvoiceUpdatePayload":{"type":"object","properties":{"change_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this change; retries reuse it."},"invoice":{"type":"object","properties":{"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The invoice's own date, checked against the closing date. An update cannot change it."},"due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Omitted keeps the current due date."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false,"description":"The invoice's customer. An update cannot change it."},"reference":{"type":"string","maxLength":255,"description":"Printed on the invoice (Xero Reference, QuickBooks CustomerMemo). Cleaned before use: line breaks and tabs become one space, other control characters are removed, surrounding spaces are trimmed. Omitted keeps the current reference; \"\" (or empty after cleaning) clears it. Refused with accounting.operation_disabled until the provider's invoice reference capability is enabled."},"private_note":{"type":"string","maxLength":4000,"description":"Internal note; omitted keeps the current note."},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"item":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"description":{"type":"string","maxLength":4000,"description":"Omitted keeps the current description."},"quantity":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,6})?$"},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"quantity x unit_price, rounded half-up to the cent."},"tax_code":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_line_id","item","quantity","unit_price","amount","tax_code"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["issue_date","currency","customer","lines"],"additionalProperties":false},"expected_totals":{"type":"object","properties":{"net_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_tax":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string","minLength":1,"maxLength":128},"component":{"type":"string","minLength":1,"maxLength":100,"description":"Provider rate name within the tax code."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$"},"taxable_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["net_amount","total_tax","total_amount"],"additionalProperties":false},"before":{"type":"object","properties":{"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."},"totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["expected_revision","totals"],"additionalProperties":false,"description":"The invoice as the ERP last saw it verified."}},"required":["change_id","invoice","expected_totals","before"],"additionalProperties":false},"AccountingPaymentCreatePayload":{"type":"object","properties":{"payment":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"payment_method":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as payment_method. Optional: omitted, QuickBooks records the payment with no payment method; Xero ignores it."},"deposit_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as deposit_account. Optional for QuickBooks only: omitted, QuickBooks deposits to its default account (Undeposited Funds), which needs a later Bank Deposit in QuickBooks. Xero requires it. A QuickBooks payment that omits payment_method or deposit_account fails with accounting.invalid_input naming the field until leaving it out is enabled for the app; sending it clears that refusal. A payment across several invoices for an app without that case enabled fails with accounting.capability_unsupported instead."},"reference":{"type":"string","minLength":1,"maxLength":21},"private_note":{"type":"string","maxLength":500}},"required":["date","amount","currency","customer"],"additionalProperties":false},"invoice":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."},"expected_balance":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"The invoice's open balance before this payment."}},"required":["erp_id","expected_revision","expected_balance"],"additionalProperties":false}},"required":["payment","invoice"],"additionalProperties":false},"AccountingRefundCreatePayload":{"type":"object","properties":{"refund":{"type":"object","properties":{"number":{"type":"string","minLength":1,"maxLength":21,"description":"Document number; required and stable."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"private_note":{"type":"string","maxLength":4000},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"original_erp_line_id":{"type":"string","minLength":1,"maxLength":128,"description":"The original invoice line this line reverses."},"item":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"description":{"type":"string","maxLength":4000},"quantity":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,6})?$"},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_code":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_line_id","original_erp_line_id","item","amount","tax_code"],"additionalProperties":false},"minItems":1,"maxItems":100},"payment_method":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as payment_method. Optional: omitted, QuickBooks records the refund with no payment method (until leaving it out is enabled for the app, the job fails with accounting.invalid_input naming refund.payment_method; sending it clears that refusal, but the refund can still be refused for another expanded case such as mixed funding, decided after QuickBooks reads); Xero ignores it."},"refund_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as refund_account."},"reference":{"type":"string","minLength":1,"maxLength":21}},"required":["number","date","currency","customer","lines","refund_account"],"additionalProperties":false},"expected_totals":{"type":"object","properties":{"net_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_tax":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string","minLength":1,"maxLength":128},"component":{"type":"string","minLength":1,"maxLength":100,"description":"Provider rate name within the tax code."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$"},"taxable_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["net_amount","total_tax","total_amount"],"additionalProperties":false},"original_invoice":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When sent, it must equal the provider invoice's date."},"before_totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["erp_id","before_totals"],"additionalProperties":false,"description":"The invoice this document reverses, as the ERP last saw it verified."},"original_payment":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false,"description":"The payment being refunded, as sent to accounting.payment.create."}},"required":["refund","expected_totals","original_invoice","original_payment"],"additionalProperties":false},"AccountingCreditMemoCreatePayload":{"type":"object","properties":{"credit_memo":{"type":"object","properties":{"number":{"type":"string","minLength":1,"maxLength":21,"description":"Document number; required and stable."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"private_note":{"type":"string","maxLength":4000},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string","minLength":1,"maxLength":128},"original_erp_line_id":{"type":"string","minLength":1,"maxLength":128,"description":"The original invoice line this line reverses."},"item":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"description":{"type":"string","maxLength":4000},"quantity":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,6})?$"},"unit_price":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_code":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_line_id","original_erp_line_id","item","amount","tax_code"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["number","date","currency","customer","lines"],"additionalProperties":false},"expected_totals":{"type":"object","properties":{"net_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_tax":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"total_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"tax_code":{"type":"string","minLength":1,"maxLength":128},"component":{"type":"string","minLength":1,"maxLength":100,"description":"Provider rate name within the tax code."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$"},"taxable_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"tax_amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"}},"required":["tax_code","component","rate_percent","taxable_amount","tax_amount"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["net_amount","total_tax","total_amount"],"additionalProperties":false},"original_invoice":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When sent, it must equal the provider invoice's date."},"before_totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["erp_id","before_totals"],"additionalProperties":false,"description":"The invoice this document reverses, as the ERP last saw it verified."}},"required":["credit_memo","expected_totals","original_invoice"],"additionalProperties":false},"AccountingCreditMemoApplyPayload":{"type":"object","properties":{"application":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"Credit applied to the invoice; positive."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"private_note":{"type":"string","maxLength":500}},"required":["date","amount","currency","customer"],"additionalProperties":false},"credit_memo":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}},"required":["erp_id"],"additionalProperties":false,"description":"The credit memo, as sent to accounting.credit_memo.create."},"invoice":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When sent, it must equal the provider invoice's date."},"before_totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["erp_id","before_totals"],"additionalProperties":false,"description":"The invoice the credit memo reverses, as the ERP last saw it verified."}},"required":["application","credit_memo","invoice"],"additionalProperties":false},"AccountingPaymentVoidPayload":{"type":"object","properties":{"void_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this void; retries reuse it."},"payment":{"type":"object","properties":{"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."}},"required":["expected_revision"],"additionalProperties":false,"description":"The payment as the ERP last saw it verified."}},"required":["void_id","payment"],"additionalProperties":false},"AccountingPaymentDeletePayload":{"type":"object","properties":{"delete_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this delete; retries reuse it."},"payment":{"type":"object","properties":{"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."}},"required":["expected_revision"],"additionalProperties":false,"description":"The payment as the ERP last saw it verified."}},"required":["delete_id","payment"],"additionalProperties":false},"AccountingPaymentUpdatePayload":{"type":"object","properties":{"change_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this change; retries reuse it."},"payment":{"type":"object","properties":{"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"New total, positive. Applied to the payment's invoice up to that invoice's open balance plus what this payment already applies; the rest stays unapplied as customer credit."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"New payment date. Both the current and the new date are checked against the closing date."},"payment_method":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as payment_method."},"deposit_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as deposit_account."},"reference":{"type":"string","minLength":1,"maxLength":21}},"required":["expected_revision"],"additionalProperties":false,"description":"The payment as the ERP last saw it verified, and the fields to change."}},"required":["change_id","payment"],"additionalProperties":false},"AccountingInvoiceDeletePayload":{"type":"object","properties":{"delete_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this delete; retries reuse it."},"invoice":{"type":"object","properties":{"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The invoice's own date, checked against the closing date."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"expected_revision":{"type":"string","minLength":1,"maxLength":64,"description":"The opaque revision from the last neutral result for this document."},"before_totals":{"$ref":"#/components/schemas/AccountingBeforeTotals"}},"required":["issue_date","currency","customer","expected_revision","before_totals"],"additionalProperties":false}},"required":["delete_id","invoice"],"additionalProperties":false},"AccountingPrepaymentCreatePayload":{"type":"object","properties":{"prepayment":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The day the money was received."},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"customer":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128}},"required":["erp_id"],"additionalProperties":false},"deposit_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as deposit_account (the bank or clearing account the money went to). Xero requires it; QuickBooks applies its default (Undeposited Funds) when omitted, under the same rule as accounting.payment.create."},"payment_method":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as payment_method. QuickBooks only; Xero ignores it."},"reference":{"type":"string","minLength":1,"maxLength":21},"private_note":{"type":"string","maxLength":500}},"required":["date","amount","currency","customer"],"additionalProperties":false}},"required":["prepayment"],"additionalProperties":false},"AccountingPrepaymentApplyPayload":{"type":"object","properties":{"prepayment":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The prepayment, as sent to accounting.prepayment.create."}},"required":["erp_id"],"additionalProperties":false},"invoice":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"An invoice written through this API, same customer and currency."}},"required":["erp_id"],"additionalProperties":false},"application":{"type":"object","properties":{"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"The amount of this prepayment applied to the invoice, at most its remaining credit and the invoice's open balance (the provider's own limits)."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Xero records it on the allocation (it may move it to the invoice date). QuickBooks has no application date: the prepayment keeps its own date."}},"required":["amount"],"additionalProperties":false}},"required":["prepayment","invoice","application"],"additionalProperties":false},"AccountingPrepaymentUnapplyPayload":{"type":"object","properties":{"unapply_id":{"type":"string","minLength":1,"maxLength":255,"description":"Stable ERP id of this unapply (1-255 characters); retries reuse it. A refused unapply may be sent again under a new unapply_id."}},"required":["unapply_id"],"additionalProperties":false},"AccountingPrepaymentRefundPayload":{"type":"object","properties":{"prepayment":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128,"description":"The prepayment the money is returned from."}},"required":["erp_id"],"additionalProperties":false},"refund":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"At most the prepayment's remaining credit."},"refund_account":{"type":"string","minLength":1,"maxLength":128,"description":"ERP code mapped as refund_account (the bank the money leaves)."},"reference":{"type":"string","minLength":1,"maxLength":21}},"required":["date","amount","refund_account"],"additionalProperties":false}},"required":["prepayment","refund"],"additionalProperties":false},"AccountingPrepaymentVoidPayload":{"type":"object","properties":{"void_id":{"type":"string","minLength":1,"maxLength":128,"description":"Stable ERP id of this void; retries reuse it. Refused while the prepayment has an open application or refund."}},"required":["void_id"],"additionalProperties":false},"AccountingOperationStatus":{"type":"object","properties":{"job_id":{"type":"string"},"operation":{"type":"string"},"erp_id":{"type":"string"},"provider_key":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","dead_lettered","cancelled","manually_resolved"],"x-ir-enum-open":true,"description":"Job lifecycle state; treat an unknown state as not finished.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"provider_detail":{"type":"string"},"message":{"type":"string","description":"Human-readable reason, for logs and for the ERP user, when the runtime has one it can share: its own refusal text, and for a provider refusal what the provider said (QuickBooks: Fault Message, Detail and error code). Absent for internal failures. Free text that may change; switch on `code`, never on this."},"reason":{"type":"string","enum":["provider_unsupported","not_offered_yet","not_enabled_for_app","disabled","disabled_for_tenant","disabled_for_connection","misconfigured","reconnect_required","unavailable","mapping_changed"],"x-ir-enum-open":true,"description":"Why the operation was refused. For accounting.operation_disabled and accounting.capability_unsupported, the capabilities endpoint's reason (provider_unsupported, not_offered_yet, not_enabled_for_app, disabled, disabled_for_tenant, disabled_for_connection, misconfigured, reconnect_required, unavailable). mapping_changed (with accounting.document_unlinked, on a cancelled job): the ERP prepayment of an accounting.prepayment.apply was re-bound to another credit after the request was accepted; nothing was sent; resend under a new idempotency_key. Treat an unknown reason as refused.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"candidate_provider_id":{"type":"string","description":"For accounting.document_exists: the existing provider document with the same number, or the existing customer or item with the same name or code. Renumber in the ERP; link applies only to an invoice the runtime created through quickbooks() on this connection; bind an existing customer or item with PUT /mappings. For accounting.refund_incomplete: the refund's credit note, open in the provider, whose cash refund was not written; resume the refund with the same erp_id, a new idempotency key and the identical body, never under a new erp_id."}},"required":["code","provider_detail"]},"result":{"$ref":"#/components/schemas/AccountingResult"}},"required":["job_id","operation","erp_id","provider_key","status","error","result"]},"AccountingResult":{"type":["object","null"],"properties":{"provider_key":{"type":"string"},"document_type":{"type":"string","enum":["customer","item","invoice","payment","refund","credit_memo","credit_application","prepayment","prepayment_application"],"x-ir-enum-open":true,"description":"Neutral document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"erp_id":{"type":"string"},"provider_id":{"type":"string"},"revision":{"type":"string","description":"Opaque. Send it back as expected_revision on the next write."},"provider_account_id":{"type":"string"},"provider_verified":{"type":"boolean","enum":[true]},"name":{"type":"string"},"currency":{"type":"string"},"net_amount":{"type":"string"},"total_tax":{"type":"string"},"total_amount":{"type":"string"},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/AccountingResultTaxLine"},"description":"Invoice create and update: the per-rate tax the provider stored. Send it back, with net_amount, total_tax and total_amount, as before.totals on the next update or void. Absent on results recorded before it was added; read the document to get it."},"lines":{"type":"array","items":{"type":"object","properties":{"erp_line_id":{"type":"string"},"provider_line_id":{"type":"string"}},"required":["erp_line_id","provider_line_id"]}},"status":{"type":"string","enum":["open","voided"],"x-ir-enum-open":true,"description":"Document status after this write, present when the write decides it (an update or void); new values may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"balance":{"type":"string","description":"Open balance after this write; for a credit memo, its unapplied credit."},"due_date":{"type":"string","description":"Invoice update: the due date (YYYY-MM-DD) the provider stored, from the verified read-back. Absent on results recorded before it was added."},"reference":{"type":"string","description":"Invoice create or update whose request carried `reference`: the reference the provider stored, from the verified read-back (\"\" when cleared). Absent when the request did not carry one."},"unapplied_amount":{"type":"string","description":"For a payment update: the amount left unapplied (customer credit) after the update."},"invoice":{"type":"object","properties":{"erp_id":{"type":"string"},"provider_id":{"type":"string"},"balance":{"type":"string"},"revision":{"type":"string","description":"Payment update: the invoice's revision from the provider read."}},"required":["erp_id","provider_id","balance"],"description":"For a payment or credit application: the invoice it settled and its verified balance."},"credit_memo":{"type":"object","properties":{"erp_id":{"type":"string"},"provider_id":{"type":"string"},"balance":{"type":"string"}},"required":["erp_id","provider_id","balance"],"description":"For a credit application: the credit memo applied and its unapplied credit."},"payment_provider_id":{"type":"string","description":"For a refund the provider records as two documents (Xero: a credit note and its cash refund): the cash refund's provider id. provider_id is then the credit note."},"side_effects":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["applied_payments_left_unapplied","excess_left_unapplied","credit_note_created"],"x-ir-enum-open":true,"description":"An effect on another document: applied_payments_left_unapplied (a payment applied to the invoice stays in the provider, unapplied), excess_left_unapplied (what the invoice cannot take stays unapplied as customer credit), credit_note_created (the provider records a refund as a credit note plus a cash refund).\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"document_type":{"type":"string","enum":["payment","credit_note"],"x-ir-enum-open":true,"description":"The kind of document affected.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"erp_id":{"type":["string","null"]},"provider_id":{"type":"string"},"amount":{"type":["string","null"]}},"required":["type","document_type","erp_id","provider_id","amount"]},"description":"Effects this write had on other documents, as the verified result shows them: excess_left_unapplied (payment update: the amount left as customer credit on the payment), credit_note_created (a refund the provider records as a credit note plus a cash refund: the credit note). Empty when none. Effects a result cannot measure are listed per operation in GET /v1/accounting/connections/{id}/capabilities."},"remaining":{"type":"string","description":"For a prepayment: the credit not yet applied to an invoice, as the provider holds it."},"applications":{"type":"array","items":{"type":"object","properties":{"invoice_provider_id":{"type":"string"},"amount":{"type":"string"}},"required":["invoice_provider_id","amount"]},"description":"For a prepayment or a prepayment application: the invoices the provider holds the prepayment applied to, with the amount each. Can be non-empty right after create when QuickBooks \"Automatically apply credits\" is on."},"application":{"type":"object","properties":{"amount":{"type":"string","description":"apply: the amount this application stands for; unapply: the amount removed now (less when part of it was already removed in the provider)."},"auto_applied_amount":{"type":"string","description":"apply: the part the provider had already applied by itself (QuickBooks \"Automatically apply credits\"); 0.00 otherwise."},"date":{"type":"string","description":"Xero apply: the allocation date Xero stored (YYYY-MM-DD). Absent for QuickBooks, which has no application date."}},"required":["amount","auto_applied_amount"],"description":"For a prepayment application (document_type prepayment_application): revision, remaining and applications are the prepayment's after this write. provider_id is the prepayment's for QuickBooks and Xero's AllocationID for Xero."},"prepayment":{"type":"object","properties":{"erp_id":{"type":"string"},"provider_id":{"type":"string"}},"required":["erp_id","provider_id"],"description":"For a prepayment application: the prepayment applied."},"deposit_account_ref_observed":{"type":"string","description":"QuickBooks payment create sent without deposit_account: the provider id of the deposit account QuickBooks chose (normally Undeposited Funds), as verified on read-back. Absent when deposit_account was sent."}},"required":["provider_key","document_type","erp_id","provider_id","revision","provider_account_id","provider_verified","side_effects"]},"MeetingProviders":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"provider_key":{"type":"string","example":"google-meet"},"display_name":{"type":"string"},"enabled":{"type":"boolean","description":"True when your app is set up for this provider, so your users can connect it."},"capabilities":{"$ref":"#/components/schemas/MeetingCapabilities"}},"required":["provider_key","display_name","enabled","capabilities"]}},"connections":{"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string"},"provider_key":{"type":"string"},"provider_account_id":{"type":"string"},"provider_account_name":{"type":["string","null"]}},"required":["connection_id","provider_key","provider_account_id","provider_account_name"]},"description":"The tenant's active meeting connections. Pass one as connection_id."}},"required":["providers","connections"]},"MeetingCapabilities":{"type":"object","properties":{"operations":{"type":"array","items":{"type":"string","enum":["meeting.create","meeting.update","meeting.end"],"x-ir-enum-open":true,"description":"A neutral meeting operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Operations this provider supports."},"fields_honored":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Optional create fields the provider stores. Others are returned in fields_ignored."},"updatable_fields":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Fields meeting.update can change on this provider. A change to another field is refused, except timezone, which is returned in fields_ignored."},"access_levels":{"type":"array","items":{"type":"string","enum":["open","trusted","restricted"],"x-ir-enum-open":true,"description":"An access level.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Access levels the provider can apply. A create or update asking for another is refused."},"link_revocable":{"type":"boolean","description":"True when meeting.end also makes the join link unusable. False: the link stays valid but the meeting is ended and restricted."},"personal_accounts":{"type":"boolean","description":"True when personal (consumer) accounts can connect, not only work accounts."},"artifacts":{"type":["object","null"],"properties":{"recordings":{"type":"boolean","description":"True when recordings are listed."},"transcripts":{"type":"boolean","description":"True when transcripts are listed."},"view_links":{"type":"boolean","description":"True when a ready recording or transcript comes with a browser link."}},"required":["recordings","transcripts","view_links"],"description":"What GET .../meetings/{meeting_ref}/artifacts returns after a meeting. Null: this provider has no recordings or transcripts read (the read answers status unsupported)."}},"required":["operations","fields_honored","updatable_fields","access_levels","link_revocable","personal_accounts","artifacts"]},"MeetingOperationStatus":{"type":"object","properties":{"job_id":{"type":"string"},"operation":{"type":"string","enum":["meeting.create","meeting.update","meeting.end"],"x-ir-enum-open":true,"description":"The neutral operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"meeting_ref":{"type":"string"},"external_ref":{"type":"string"},"provider_key":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed","dead_lettered","cancelled","manually_resolved"],"x-ir-enum-open":true,"description":"Job lifecycle state; treat an unknown state as not finished.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"idempotent_replay":{"type":"boolean","description":"True when this answer is an earlier request's operation (same idempotency_key)."},"existing_meeting":{"type":"boolean","description":"True when external_ref already named a meeting (or meeting_ref was already ending or ended): this is that earlier operation, and nothing new was sent to the provider."},"polling_url":{"type":"string","description":"Sign and GET this to read the operation again."},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"provider_detail":{"type":"string"},"message":{"type":"string","description":"Human-readable reason when the runtime has one it can share. Switch on code, never on this."}},"required":["code","provider_detail"]},"update_result":{"type":["object","null"],"properties":{"fields_applied":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Changes the provider applied, as its answer showed them."},"fields_ignored":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Changes the provider did not apply or does not store (e.g. timezone)."}},"required":["fields_applied","fields_ignored"],"description":"For a finished meeting.update: what this update changed. Null otherwise."},"meeting":{"$ref":"#/components/schemas/Meeting"}},"required":["job_id","operation","meeting_ref","external_ref","provider_key","status","idempotent_replay","existing_meeting","polling_url","error","update_result","meeting"]},"Meeting":{"type":"object","properties":{"meeting_ref":{"type":"string","description":"The runtime's id for this meeting."},"external_ref":{"type":"string"},"connection_id":{"type":"string"},"provider_key":{"type":"string"},"status":{"type":"string","enum":["creating","active","ending","ended","failed"],"x-ir-enum-open":true,"description":"creating: the create is in flight. active: the join link is ready (an update may be in flight). ending: an end is in flight. ended: the meeting was ended. failed: the create failed; a new create with the same external_ref may be sent.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"provider_meeting_id":{"type":["string","null"]},"join_url":{"type":["string","null"],"description":"Send this link to the attendees."},"meeting_code":{"type":["string","null"]},"dial_in":{"type":["array","null"],"items":{"type":"object","properties":{"number":{"type":"string"},"pin":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["number","pin","country"]}},"fields_applied":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Create fields the provider applied."},"fields_ignored":{"type":"array","items":{"type":"string","enum":["title","start","end","timezone","access"],"x-ir-enum-open":true,"description":"A neutral meeting field.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"description":"Create fields you sent that this provider does not store (for example a title on Google Meet)."},"title":{"type":["string","null"],"description":"The title as the provider last confirmed it (create or update). Null when the provider stores none or none was set."},"start":{"type":["string","null"],"description":"Start time as the provider last confirmed it (ISO 8601)."},"end":{"type":["string","null"],"description":"End time as the provider last confirmed it (ISO 8601)."},"access":{"type":["string","null"],"enum":["open","trusted","restricted",null],"x-ir-enum-open":true,"description":"Access level as the provider last confirmed it; null when unknown.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"update_in_progress":{"type":"boolean","description":"True while a meeting.update is in flight; another update or an end waits for it."},"created_at":{"type":"string","description":"ISO 8601."},"updated_at":{"type":"string","description":"ISO 8601."}},"required":["meeting_ref","external_ref","connection_id","provider_key","status","provider_meeting_id","join_url","meeting_code","dial_in","fields_applied","fields_ignored","title","start","end","access","update_in_progress","created_at","updated_at"]},"MeetingOperationRequest":{"oneOf":[{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"The meeting connection to use (a tenant may hold several meeting providers)."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Retry with the same key and body after a lost response."},"operation":{"type":"string","enum":["meeting.create"]},"meeting":{"$ref":"#/components/schemas/MeetingDetails"}},"required":["tenant_id","connection_id","idempotency_key","operation","meeting"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"The meeting connection to use (a tenant may hold several meeting providers)."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Retry with the same key and body after a lost response."},"operation":{"type":"string","enum":["meeting.update"]},"meeting_ref":{"type":"string","minLength":1,"maxLength":64,"description":"The meeting_ref returned when the meeting was created."},"changes":{"$ref":"#/components/schemas/MeetingChanges"}},"required":["tenant_id","connection_id","idempotency_key","operation","meeting_ref","changes"],"additionalProperties":false},{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"connection_id":{"type":"string","minLength":1,"description":"The meeting connection to use (a tenant may hold several meeting providers)."},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Retry with the same key and body after a lost response."},"operation":{"type":"string","enum":["meeting.end"]},"meeting_ref":{"type":"string","minLength":1,"maxLength":64,"description":"The meeting_ref returned when the meeting was created."}},"required":["tenant_id","connection_id","idempotency_key","operation","meeting_ref"],"additionalProperties":false}]},"MeetingDetails":{"type":"object","properties":{"external_ref":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[^\\p{Cc}]+$/u","description":"Your own id for this meeting, unique per tenant. A create naming an external_ref that already has a meeting returns that meeting instead of creating another."},"title":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^\\p{Cc}]+$/u"},"start":{"type":"string","format":"date-time","description":"ISO 8601 date-time with an offset, e.g. 2026-11-20T15:00:00-05:00."},"end":{"type":"string","format":"date-time","description":"ISO 8601 date-time with an offset, e.g. 2026-11-20T15:00:00-05:00."},"timezone":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_+\\-/]+$","description":"IANA time zone the meeting is shown in, e.g. America/Toronto."},"access":{"type":"string","enum":["open","trusted","restricted"],"description":"Who can join without being let in: open (anyone with the link), trusted (the organizer's organization and invited people), restricted (only invited people). The provider's default when absent. Refused when the provider cannot apply it (see access_levels in GET /v1/meetings/providers)."}},"required":["external_ref"],"additionalProperties":false},"MeetingChanges":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^\\p{Cc}]+$/u"},"start":{"type":"string","format":"date-time","description":"ISO 8601 date-time with an offset, e.g. 2026-11-20T15:00:00-05:00."},"end":{"type":"string","format":"date-time","description":"ISO 8601 date-time with an offset, e.g. 2026-11-20T15:00:00-05:00."},"timezone":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_+\\-/]+$","description":"IANA time zone the meeting is shown in, e.g. America/Toronto."},"access":{"type":"string","enum":["open","trusted","restricted"],"description":"Who can join without being let in: open (anyone with the link), trusted (the organizer's organization and invited people), restricted (only invited people). The provider's default when absent. Refused when the provider cannot apply it (see access_levels in GET /v1/meetings/providers)."}},"additionalProperties":false},"MeetingArtifacts":{"type":"object","properties":{"meeting_ref":{"type":"string"},"status":{"type":"string","enum":["available","pending","none","unsupported"],"x-ir-enum-open":true,"description":"available: at least one recording or transcript is ready. pending: a call is running, a file is processing, or the meeting ended recently and one may still appear. none: nothing was recorded (see reason). unsupported: this provider has no recordings or transcripts read.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"reason":{"type":["string","null"],"description":"Why status is none: not_recorded_or_not_permitted (nobody recorded, or the account cannot record; Google Meet cannot tell which) or processing_timeout (a file was still processing 24 hours after the meeting). Null otherwise."},"final":{"type":"boolean","description":"True when this answer will not change any more; stop checking."},"stale":{"type":"boolean","description":"True when the provider could not be asked just now (rate limit, outage or connection not active) and this is the last answer read."},"conferences":{"type":"array","items":{"type":"object","properties":{"started_at":{"type":["string","null"],"description":"ISO 8601."},"ended_at":{"type":["string","null"],"description":"ISO 8601; null while the call is running."}},"required":["started_at","ended_at"]},"description":"Each call held in the meeting, newest first."},"recordings":{"type":"array","items":{"$ref":"#/components/schemas/MeetingArtifact"}},"transcripts":{"type":"array","items":{"$ref":"#/components/schemas/MeetingArtifact"}},"checked_at":{"type":["string","null"],"description":"When the provider was last asked (ISO 8601). Null for unsupported."}},"required":["meeting_ref","status","reason","final","stale","conferences","recordings","transcripts","checked_at"]},"UsageResponse":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"generated_at":{"type":"integer","minimum":0},"window":{"type":"object","properties":{"since":{"type":"integer","minimum":0},"until":{"type":"integer","minimum":0},"minutes":{"type":"integer","minimum":1,"maximum":10080}},"required":["since","until","minutes"]},"source":{"type":"string","enum":["sync_jobs"]},"basis":{"type":"string","enum":["created_cohort_current_state"]},"totals":{"$ref":"#/components/schemas/UsageCounts"},"breakdown":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/UsageCounts"},{"type":"object","properties":{"provider_key":{"type":"string"},"operation_key":{"type":"string"}},"required":["provider_key","operation_key"]}]},"maxItems":200},"provider_http_attempts":{"type":"object","properties":{"availability":{"type":"string","enum":["unavailable"]},"count":{"type":"null"}},"required":["availability","count"],"description":"No exact provider HTTP attempt ledger is available; job retry counts and sampled telemetry are not call counts."},"limits":{"type":"object","properties":{"max_jobs":{"type":"integer","exclusiveMinimum":0,"example":10000},"max_breakdown_groups":{"type":"integer","exclusiveMinimum":0,"example":200}},"required":["max_jobs","max_breakdown_groups"]}},"required":["app_id","tenant_id","generated_at","window","source","basis","totals","breakdown","provider_http_attempts","limits"]},"UsageCounts":{"type":"object","properties":{"jobs_created":{"type":"integer","minimum":0,"description":"Retained jobs created in [window.since, window.until), including automatic and replay jobs. Not API submissions or provider calls."},"jobs_completed":{"type":"integer","minimum":0,"description":"Jobs in this creation cohort currently in completed status. Not all completions during the window."},"by_status":{"type":"object","properties":{"queued":{"type":"integer","minimum":0},"processing":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"dead_lettered":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0},"manually_resolved":{"type":"integer","minimum":0}},"required":["queued","processing","completed","failed","dead_lettered","cancelled","manually_resolved"]}},"required":["jobs_created","jobs_completed","by_status"]},"SyncJobsListResponse":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/SyncJobPublicDTO"}},"next_cursor":{"type":["string","null"]}},"required":["jobs","next_cursor"]},"SyncJobPublicDTO":{"type":"object","properties":{"id":{"type":"string"},"app_id":{"type":"string"},"tenant_id":{"type":"string"},"provider_key":{"type":"string"},"connection_id":{"type":"string"},"operation_key":{"type":"string"},"recipe_key":{"type":["string","null"]},"recipe_version":{"type":["integer","null"]},"object_type":{"type":["string","null"]},"internal_object_id":{"type":["string","null"]},"external_object_id":{"type":["string","null"]},"status":{"type":"string","enum":["queued","processing","completed","failed","dead_lettered","cancelled","manually_resolved"],"x-ir-enum-open":true,"description":"Lifecycle state of the job.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"attempt_count":{"type":"integer","minimum":0},"last_error_code":{"$ref":"#/components/schemas/SyncJobFailureCode"},"created_at":{"type":"integer"},"completed_at":{"type":["integer","null"]}},"required":["id","app_id","tenant_id","provider_key","connection_id","operation_key","recipe_key","recipe_version","object_type","internal_object_id","external_object_id","status","attempt_count","last_error_code","created_at","completed_at"]},"SyncJobFailureCode":{"type":["string","null"],"description":"Machine-readable asynchronous failure code. Switch on this value, never on a human message.\n\nThis is an open string: other job failure codes may appear, and clients must tolerate values they do not recognise.\n\nFor the QuickBooks recipe-v2 tax outcomes below, `terminal` means the runtime does not automatically retry the failed delivery. `bounded-retryable` means the runtime retries automatically up to its attempt ceiling; exhaustion can still leave the job `dead_lettered`, so do not submit a duplicate operation while those retries are active.\n\n| Code | Disposition | Cause | Caller remedy |\n|---|---|---|---|\n| `invoice_runtime_marker_forbidden` | terminal | The exact Invoice document contains request-specific runtime marker evidence from a historical writer. | For fresh invalid input, restore the caller's marker-free business document. If a reservation already exists, preserve it unchanged and perform operator reconciliation before any replay. |\n| `invoice_payload_conflict` | terminal | The stored job payload was altered, or this internal invoice already has a reservation for different input. | Restore the immutable original input and investigate the conflict. Do not change the idempotency key to recreate an invoice that may already exist. |\n| `invoice_company_mismatch` | terminal | The admitted job or reservation company differs from the current authorized connection, or the authoritative admission pin is missing. | Restore the original company connection and inspect the job and reservation evidence before operator replay. Never repin or re-key an uncertain write to another company. |\n| `invoice_identity_unavailable` | terminal | A historical Invoice reservation lacks an immutable payload fingerprint or original provider deduplication token. | Operator reconciliation is required using the original company and provider evidence. Do not infer the original payload, mint a new request token, or reset the recovery clock. |\n| `invoice_reference_not_enabled` | terminal | The Invoice carries a reference (CustomerMemo from a neutral invoice reference) and the provider's invoice reference capability was disabled after admission. Raised only on a first attempt: no provider call had been started for this request (no reservation, or one never stamped as sent), and the refusal opens none, so nothing was written. A retry of a write that may have reached the provider never gets this code. | Because nothing was written, resend the document without the reference (for a neutral request, under a new idempotency key with the same erp_id), or ask the operator to enable the invoice reference capability and resend. |\n| `ccdo.invoice_reservation_raced` | bounded-retryable | An existing reservation appeared during Invoice reservation opening; no provider create was sent by this attempt. | Allow bounded retry through the authoritative reservation recovery path; retain the original request token and first-call clock. |\n| `job.input_missing` | terminal | The immutable job input is still missing after the 15-minute admission recovery grace. Publication is refused. | Inspect the original job and reservation before retrying. A prior delivery or replay may have created an invoice; do not blindly submit with a new identity. Restore the original accepted payload or reconcile the provider outcome first. |\n| `job.input_reference_invalid` | terminal | The job input reference is outside its tenant namespace or is not a supported input object. Publication is refused. | Investigate stored job integrity and any prior provider outcome; never repair a reference by borrowing another tenant's payload. |\n| `job.payload_fingerprint_conflict` | terminal | The recovered input does not match the accepted Invoice fingerprint, or a legacy Invoice job lacks that fingerprint. Publication is refused. | Reconcile the accepted input and any existing provider invoice. Do not replace the immutable input, adopt a new identity, or automatically recreate the invoice. |\n| `job.recipe_missing` | terminal | The durable job is missing its executable recipe identity. Publication is refused. | Inspect job integrity and any prior provider outcome before an operator-authorized recovery. |\n| `job.delivery_status_unconfirmed` | terminal | Publication or delivery status exceeded its 24-hour recovery deadline without a fresh job or step heartbeat. An invoice MAY ALREADY EXIST; this is not proof that the provider write failed. | Reconcile the original provider request and reservation before replaying. Preserve its identity and original recovery clock; never automatically recreate with a new key. Pilot clients must surface this outcome as requiring operator attention. |\n| `cf_retries_exhausted` | terminal | Queue delivery exhausted its retry budget. The terminal job state and operator record are committed together. The provider outcome may already exist. | Inspect the job steps, original request identity, and provider reservation before an operator-authorized replay; do not assume that a dead-lettered job means no invoice was created. |\n| `financial_write_tax_disabled` | terminal | The live QuickBooks preference is exactly Preferences.TaxPrefs.UsingSalesTax=false. No Invoice or RefundReceipt create is sent. | Enable sales tax in QuickBooks, then ask an operator to replay the job. |\n| `financial_write_tax_preflight_failed` | terminal | The runtime cannot confirm the live QuickBooks sales-tax preference because the read is unauthorized, rate-limited, unavailable, malformed, missing, or the wrong type. No Invoice or RefundReceipt create is sent. | Restore QuickBooks access or availability, then ask an operator to replay the job. |\n| `financial_write_currency_unsupported` | terminal | The live QuickBooks Invoice profile has a home currency other than CAD, or multicurrency enabled on a production company (a CAD sandbox company may have multicurrency enabled). No Invoice create is sent. | Use a qualified CAD company (single-currency in production), then ask an operator to replay the job. |\n| `quickbooks.invoice_document_number_exists` | terminal | Invoice v6 only: a QuickBooks Invoice (voided ones included) already uses this DocNumber. Checked inside the connection's serialized slot before any reservation, so no Invoice create is sent. The error message names candidate_provider_id. | Send the document with a different number and a new idempotency key. Linking adopts only an Invoice the runtime created, so an Invoice entered directly in QuickBooks cannot be linked. |\n| `quickbooks.invoice_document_number_unconfirmed` | bounded-retryable | Invoice v6 only: the DocNumber query failed, was throttled or returned an unusable response. No Invoice create is sent. | None while retries remain; restore QuickBooks access if it persists. |\n| `quickbooks.period_closed` | terminal | Invoice v6 only: TxnDate is on or before the QuickBooks closing date (AccountingInfoPrefs.BookCloseDate). No Invoice create is sent. | Re-date the document after the closing date, or reopen the period in QuickBooks, then submit with a new idempotency key. |\n| `quickbooks.period_unconfirmed` | bounded-retryable | Invoice v6 only: the QuickBooks closing date could not be read as a date. No Invoice create is sent. | None while retries remain; contact support (the address is in your Console footer) if it persists. |\n| `quickbooks.invoice_guard_invalid` | terminal | Invoice v6 only: the guarded Invoice has a DocNumber longer than 21 characters or no YYYY-MM-DD TxnDate. No Invoice create is sent. | Correct the document and submit with a new idempotency key. |\n| `financial_write_tax_declaration_missing` | terminal | tax_declarations is absent or does not cover every provider line exactly once. No document create is sent. | Correct the declarations and submit a new job using the current supported recipe version with a new idempotency key; replaying the immutable invalid input cannot repair it. |\n| `financial_write_tax_payload_invalid` | terminal | The document or declarations are malformed, including missing native Invoice customer/item/tax references, Invoice update selectors or root customer/items inputs, duplicate or out-of-range indexes, unknown treatments, or a missing RefundReceipt deposit account. No document create is sent. | Correct the payload and submit a new job using the current supported recipe version with a new idempotency key; replaying the immutable invalid input cannot repair it. |\n| `financial_write_tax_path_unsupported` | terminal | The request uses an unsupported calculation mode, supplies TxnTaxDetail, or contains a Group, Discount, Subtotal, or other unsupported line shape. No document create is sent. | Rebuild the payload on the supported TaxExcluded top-level sales-line path and submit a new job using the current supported recipe version with a new idempotency key. |\n| `financial_write_tax_verification_mismatch` | terminal | A successful stored-document GET does not match the immutable calculation mode and line signatures. The linked reservation is retained and no replacement create is sent. | Do not recreate automatically. Compare the stored QuickBooks document with the source request and manually reconcile the discrepancy before submitting another job. |\n| `financial_write_tax_verification_unconfirmed` | bounded-retryable | The stored-document GET is missing, unavailable, malformed, or otherwise cannot confirm the durable object identity and tax content. The linked reservation is retained and no replacement create is sent. | Allow the runtime's bounded automatic retries to finish. If they are exhausted, restore provider availability, inspect the linked document, and ask an operator to replay the job. A 401 and 429 use their separate provider.401 and ccdo.rate_limited codes. |\n\nLinked Payment recipe v2 verifies stored allocation and authoritative remaining Invoice balance before publishing a public result.\n\n| Code | Disposition | Cause | Caller remedy |\n|---|---|---|---|\n| `payment.invalid_input` | terminal | The immutable positive CAD Payment envelope is invalid. | Correct input before first admission; preserve any existing request and do not re-key uncertainty. |\n| `payment.identity_unavailable` | terminal | Original durable Payment identity/company or verification coordinates are missing. | Reconcile historical provider evidence using the original company and request. |\n| `payment.parent_invoice_mismatch` | terminal | The Invoice is not linked under this exact app/tenant/native company, or the frozen company differs. | Restore the original native scope; do not repin an existing request after reconnect. |\n| `payment.invoice_snapshot_mismatch` | terminal | Current Invoice customer/currency/version or remaining balance differs from the approved snapshot. | Use operator GET-only reconciliation for uncertainty. Prepare new input only for a separate legitimate payment. |\n| `payment.reference_inactive` | terminal | The deposit account or payment method is inactive or unsupported. | Resolve reference drift and reconcile any prior provider write before a new request. |\n| `payment.verification_mismatch` | terminal | Stored Payment allocation/references or remaining Invoice balance differs from the original request. | A provider Payment may already exist. Compare native records; do not recreate or change its key. |\n| `payment.verification_unconfirmed` | bounded-retryable | Native provider reference or Payment/Invoice read-back is unusable. | Allow bounded retries of the original job, then restore reads and reconcile existing native evidence. |\n| `payment.status_refresh_unconfirmed` | bounded-retryable | The verified Payment's durable status projection could not be refreshed. | Retry the original job; its linked reservation prevents a replacement provider write. |\n\nFor Google Calendar read jobs, the same disposition terms apply to these grant, provider, persistence, and kill-switch outcomes.\n\n| Code | Disposition | Cause | Caller remedy |\n|---|---|---|---|\n| `operation_not_enabled` | terminal | The Calendar operation was disabled after admission and before execution. | Ask an operator to enable the operation, then submit a new root read. |\n| `oauth.lifecycle_busy` | bounded-retryable | A callback, refresh, or disconnect currently owns the grant lifecycle. | Allow bounded retry of the same job after the lifecycle owner completes. |\n| `recipe_result.invalid_json` | terminal | The Calendar page result could not be serialized as valid bounded JSON for publication. | Investigate the publication failure, then submit a new root read after correction. |\n| `recipe_result.too_large` | terminal | The valid Calendar page result exceeded the 32 KiB public job-result publication limit. | Submit a new root read with a smaller page_size so its public result stays bounded. |\n| `calendar.invalid_input` | terminal | The durable Calendar job input is invalid for its frozen recipe. | Correct the request before retrying. |\n| `calendar.unsupported_representation` | terminal | The event read requests an unsupported representation. | Use the series-and-exceptions representation. |\n| `calendar.grant_not_found` | terminal | The job's scoped Calendar grant no longer exists. | Treat the grant as unavailable. |\n| `calendar.resource_not_found` | terminal | The selected Calendar resource no longer exists. | Treat the resource as unavailable. |\n| `calendar.insufficient_scopes` | terminal | The current grant lacks the scope required by the operation. | Reconnect and grant the required scope. |\n| `calendar.resource_denied` | terminal | The job, grant, continuation, or resource binding no longer matches. | Use an authorized selected resource. |\n| `calendar.resource_detached` | terminal | The selected Calendar resource was detached before execution. | Select the resource again with a new intent. |\n| `calendar.grant_revoked` | terminal | The Calendar grant was revoked before execution. | Start a new consent ceremony. |\n| `calendar.grant_disabled` | terminal | Calendar admission is disabled for this app or registration. | Ask an operator to enable Calendar admission. |\n| `calendar.generation_changed` | terminal | The grant callback generation changed after the job was admitted. | Start a new root read on the current grant. |\n| `calendar.reconnect_required` | terminal | The current Calendar authorization requires reconnection. | Reconnect, rediscover, and reselect. |\n| `calendar.result_expired` | terminal | The root traversal expired before this job could publish its result. | Start a new root listing or read. |\n| `calendar.page_expired` | terminal | The bounded Calendar page expired before it could be staged. | Start a new root listing or read. |\n| `calendar.page_pending` | terminal | The referenced Calendar page is not yet in a completed state. | Poll the associated job before fetching the page. |\n| `calendar.state_unavailable` | bounded-retryable | Required Calendar state could not be read or persisted safely. | Retry the same signed intent with backoff. |\n| `calendar.invalid_continuation` | terminal | The continuation is malformed or no longer matches its parent page. | Start a new root listing or read. |\n| `calendar.continuation_expired` | terminal | The queued resume job references a continuation whose traversal window has expired. | Start a new root listing or read. |\n| `calendar.continuation_not_found` | terminal | The queued resume job no longer matches an available parent continuation. | Start a new root listing or read. |\n| `calendar.forbidden` | terminal | Google denied access to the requested Calendar resource. | Reconnect or choose a readable resource. |\n| `calendar.not_found` | terminal | Google reports that the requested Calendar resource does not exist. | Treat the provider resource as unavailable. |\n| `calendar.unexpected_status` | terminal | Google returned a response status outside the supported Calendar contract. | Start a new read after operator review. |\n| `calendar.response_too_large` | terminal | The bounded Google Calendar response exceeded the accepted size. | Use a smaller new root page size. |\n| `calendar.malformed_response` | terminal | Google returned a Calendar response that failed structural validation. | Start a new read after operator review. |\n| `calendar.rate_limited` | bounded-retryable | Calendar execution was refused by local quota or throttled by Google. | Retry with bounded backoff. |\n| `calendar.unavailable` | bounded-retryable | Calendar execution or Google Calendar is temporarily unavailable. | Retry with bounded backoff. |\n| `calendar.transport_error` | bounded-retryable | The Google Calendar request failed before a valid response arrived. | Retry with bounded backoff. |\n| `calendar.timeout` | bounded-retryable | The bounded Google Calendar request exceeded its timeout. | Retry with bounded backoff. |","x-ir-quickbooks-payment-job-errors":[{"code":"payment.invalid_input","disposition":"terminal","cause":"The immutable positive CAD Payment envelope is invalid.","remedy":"Correct input before first admission; preserve any existing request and do not re-key uncertainty."},{"code":"payment.identity_unavailable","disposition":"terminal","cause":"Original durable Payment identity/company or verification coordinates are missing.","remedy":"Reconcile historical provider evidence using the original company and request."},{"code":"payment.parent_invoice_mismatch","disposition":"terminal","cause":"The Invoice is not linked under this exact app/tenant/native company, or the frozen company differs.","remedy":"Restore the original native scope; do not repin an existing request after reconnect."},{"code":"payment.invoice_snapshot_mismatch","disposition":"terminal","cause":"Current Invoice customer/currency/version or remaining balance differs from the approved snapshot.","remedy":"Use operator GET-only reconciliation for uncertainty. Prepare new input only for a separate legitimate payment."},{"code":"payment.reference_inactive","disposition":"terminal","cause":"The deposit account or payment method is inactive or unsupported.","remedy":"Resolve reference drift and reconcile any prior provider write before a new request."},{"code":"payment.verification_mismatch","disposition":"terminal","cause":"Stored Payment allocation/references or remaining Invoice balance differs from the original request.","remedy":"A provider Payment may already exist. Compare native records; do not recreate or change its key."},{"code":"payment.verification_unconfirmed","disposition":"bounded-retryable","cause":"Native provider reference or Payment/Invoice read-back is unusable.","remedy":"Allow bounded retries of the original job, then restore reads and reconcile existing native evidence."},{"code":"payment.status_refresh_unconfirmed","disposition":"bounded-retryable","cause":"The verified Payment's durable status projection could not be refreshed.","remedy":"Retry the original job; its linked reservation prevents a replacement provider write."}],"x-ir-quickbooks-tax-job-errors":[{"code":"invoice_runtime_marker_forbidden","disposition":"terminal","cause":"The exact Invoice document contains request-specific runtime marker evidence from a historical writer.","remedy":"For fresh invalid input, restore the caller's marker-free business document. If a reservation already exists, preserve it unchanged and perform operator reconciliation before any replay."},{"code":"invoice_payload_conflict","disposition":"terminal","cause":"The stored job payload was altered, or this internal invoice already has a reservation for different input.","remedy":"Restore the immutable original input and investigate the conflict. Do not change the idempotency key to recreate an invoice that may already exist."},{"code":"invoice_company_mismatch","disposition":"terminal","cause":"The admitted job or reservation company differs from the current authorized connection, or the authoritative admission pin is missing.","remedy":"Restore the original company connection and inspect the job and reservation evidence before operator replay. Never repin or re-key an uncertain write to another company."},{"code":"invoice_identity_unavailable","disposition":"terminal","cause":"A historical Invoice reservation lacks an immutable payload fingerprint or original provider deduplication token.","remedy":"Operator reconciliation is required using the original company and provider evidence. Do not infer the original payload, mint a new request token, or reset the recovery clock."},{"code":"invoice_reference_not_enabled","disposition":"terminal","cause":"The Invoice carries a reference (CustomerMemo from a neutral invoice reference) and the provider's invoice reference capability was disabled after admission. Raised only on a first attempt: no provider call had been started for this request (no reservation, or one never stamped as sent), and the refusal opens none, so nothing was written. A retry of a write that may have reached the provider never gets this code.","remedy":"Because nothing was written, resend the document without the reference (for a neutral request, under a new idempotency key with the same erp_id), or ask the operator to enable the invoice reference capability and resend."},{"code":"ccdo.invoice_reservation_raced","disposition":"bounded-retryable","cause":"An existing reservation appeared during Invoice reservation opening; no provider create was sent by this attempt.","remedy":"Allow bounded retry through the authoritative reservation recovery path; retain the original request token and first-call clock."},{"code":"job.input_missing","disposition":"terminal","cause":"The immutable job input is still missing after the 15-minute admission recovery grace. Publication is refused.","remedy":"Inspect the original job and reservation before retrying. A prior delivery or replay may have created an invoice; do not blindly submit with a new identity. Restore the original accepted payload or reconcile the provider outcome first."},{"code":"job.input_reference_invalid","disposition":"terminal","cause":"The job input reference is outside its tenant namespace or is not a supported input object. Publication is refused.","remedy":"Investigate stored job integrity and any prior provider outcome; never repair a reference by borrowing another tenant's payload."},{"code":"job.payload_fingerprint_conflict","disposition":"terminal","cause":"The recovered input does not match the accepted Invoice fingerprint, or a legacy Invoice job lacks that fingerprint. Publication is refused.","remedy":"Reconcile the accepted input and any existing provider invoice. Do not replace the immutable input, adopt a new identity, or automatically recreate the invoice."},{"code":"job.recipe_missing","disposition":"terminal","cause":"The durable job is missing its executable recipe identity. Publication is refused.","remedy":"Inspect job integrity and any prior provider outcome before an operator-authorized recovery."},{"code":"job.delivery_status_unconfirmed","disposition":"terminal","cause":"Publication or delivery status exceeded its 24-hour recovery deadline without a fresh job or step heartbeat. An invoice MAY ALREADY EXIST; this is not proof that the provider write failed.","remedy":"Reconcile the original provider request and reservation before replaying. Preserve its identity and original recovery clock; never automatically recreate with a new key. Pilot clients must surface this outcome as requiring operator attention."},{"code":"cf_retries_exhausted","disposition":"terminal","cause":"Queue delivery exhausted its retry budget. The terminal job state and operator record are committed together. The provider outcome may already exist.","remedy":"Inspect the job steps, original request identity, and provider reservation before an operator-authorized replay; do not assume that a dead-lettered job means no invoice was created."},{"code":"financial_write_tax_disabled","disposition":"terminal","cause":"The live QuickBooks preference is exactly Preferences.TaxPrefs.UsingSalesTax=false. No Invoice or RefundReceipt create is sent.","remedy":"Enable sales tax in QuickBooks, then ask an operator to replay the job."},{"code":"financial_write_tax_preflight_failed","disposition":"terminal","cause":"The runtime cannot confirm the live QuickBooks sales-tax preference because the read is unauthorized, rate-limited, unavailable, malformed, missing, or the wrong type. No Invoice or RefundReceipt create is sent.","remedy":"Restore QuickBooks access or availability, then ask an operator to replay the job."},{"code":"financial_write_currency_unsupported","disposition":"terminal","cause":"The live QuickBooks Invoice profile has a home currency other than CAD, or multicurrency enabled on a production company (a CAD sandbox company may have multicurrency enabled). No Invoice create is sent.","remedy":"Use a qualified CAD company (single-currency in production), then ask an operator to replay the job."},{"code":"quickbooks.invoice_document_number_exists","disposition":"terminal","cause":"Invoice v6 only: a QuickBooks Invoice (voided ones included) already uses this DocNumber. Checked inside the connection's serialized slot before any reservation, so no Invoice create is sent. The error message names candidate_provider_id.","remedy":"Send the document with a different number and a new idempotency key. Linking adopts only an Invoice the runtime created, so an Invoice entered directly in QuickBooks cannot be linked."},{"code":"quickbooks.invoice_document_number_unconfirmed","disposition":"bounded-retryable","cause":"Invoice v6 only: the DocNumber query failed, was throttled or returned an unusable response. No Invoice create is sent.","remedy":"None while retries remain; restore QuickBooks access if it persists."},{"code":"quickbooks.period_closed","disposition":"terminal","cause":"Invoice v6 only: TxnDate is on or before the QuickBooks closing date (AccountingInfoPrefs.BookCloseDate). No Invoice create is sent.","remedy":"Re-date the document after the closing date, or reopen the period in QuickBooks, then submit with a new idempotency key."},{"code":"quickbooks.period_unconfirmed","disposition":"bounded-retryable","cause":"Invoice v6 only: the QuickBooks closing date could not be read as a date. No Invoice create is sent.","remedy":"None while retries remain; contact support (the address is in your Console footer) if it persists."},{"code":"quickbooks.invoice_guard_invalid","disposition":"terminal","cause":"Invoice v6 only: the guarded Invoice has a DocNumber longer than 21 characters or no YYYY-MM-DD TxnDate. No Invoice create is sent.","remedy":"Correct the document and submit with a new idempotency key."},{"code":"financial_write_tax_declaration_missing","disposition":"terminal","cause":"tax_declarations is absent or does not cover every provider line exactly once. No document create is sent.","remedy":"Correct the declarations and submit a new job using the current supported recipe version with a new idempotency key; replaying the immutable invalid input cannot repair it."},{"code":"financial_write_tax_payload_invalid","disposition":"terminal","cause":"The document or declarations are malformed, including missing native Invoice customer/item/tax references, Invoice update selectors or root customer/items inputs, duplicate or out-of-range indexes, unknown treatments, or a missing RefundReceipt deposit account. No document create is sent.","remedy":"Correct the payload and submit a new job using the current supported recipe version with a new idempotency key; replaying the immutable invalid input cannot repair it."},{"code":"financial_write_tax_path_unsupported","disposition":"terminal","cause":"The request uses an unsupported calculation mode, supplies TxnTaxDetail, or contains a Group, Discount, Subtotal, or other unsupported line shape. No document create is sent.","remedy":"Rebuild the payload on the supported TaxExcluded top-level sales-line path and submit a new job using the current supported recipe version with a new idempotency key."},{"code":"financial_write_tax_verification_mismatch","disposition":"terminal","cause":"A successful stored-document GET does not match the immutable calculation mode and line signatures. The linked reservation is retained and no replacement create is sent.","remedy":"Do not recreate automatically. Compare the stored QuickBooks document with the source request and manually reconcile the discrepancy before submitting another job."},{"code":"financial_write_tax_verification_unconfirmed","disposition":"bounded-retryable","cause":"The stored-document GET is missing, unavailable, malformed, or otherwise cannot confirm the durable object identity and tax content. The linked reservation is retained and no replacement create is sent.","remedy":"Allow the runtime's bounded automatic retries to finish. If they are exhausted, restore provider availability, inspect the linked document, and ask an operator to replay the job. A 401 and 429 use their separate provider.401 and ccdo.rate_limited codes."}],"x-ir-calendar-job-errors":[{"code":"operation_not_enabled","disposition":"terminal","cause":"The Calendar operation was disabled after admission and before execution.","remedy":"Ask an operator to enable the operation, then submit a new root read."},{"code":"oauth.lifecycle_busy","disposition":"bounded-retryable","cause":"A callback, refresh, or disconnect currently owns the grant lifecycle.","remedy":"Allow bounded retry of the same job after the lifecycle owner completes."},{"code":"recipe_result.invalid_json","disposition":"terminal","cause":"The Calendar page result could not be serialized as valid bounded JSON for publication.","remedy":"Investigate the publication failure, then submit a new root read after correction."},{"code":"recipe_result.too_large","disposition":"terminal","cause":"The valid Calendar page result exceeded the 32 KiB public job-result publication limit.","remedy":"Submit a new root read with a smaller page_size so its public result stays bounded."},{"code":"calendar.invalid_input","disposition":"terminal","cause":"The durable Calendar job input is invalid for its frozen recipe.","remedy":"Correct the request before retrying."},{"code":"calendar.unsupported_representation","disposition":"terminal","cause":"The event read requests an unsupported representation.","remedy":"Use the series-and-exceptions representation."},{"code":"calendar.grant_not_found","disposition":"terminal","cause":"The job's scoped Calendar grant no longer exists.","remedy":"Treat the grant as unavailable."},{"code":"calendar.resource_not_found","disposition":"terminal","cause":"The selected Calendar resource no longer exists.","remedy":"Treat the resource as unavailable."},{"code":"calendar.insufficient_scopes","disposition":"terminal","cause":"The current grant lacks the scope required by the operation.","remedy":"Reconnect and grant the required scope."},{"code":"calendar.resource_denied","disposition":"terminal","cause":"The job, grant, continuation, or resource binding no longer matches.","remedy":"Use an authorized selected resource."},{"code":"calendar.resource_detached","disposition":"terminal","cause":"The selected Calendar resource was detached before execution.","remedy":"Select the resource again with a new intent."},{"code":"calendar.grant_revoked","disposition":"terminal","cause":"The Calendar grant was revoked before execution.","remedy":"Start a new consent ceremony."},{"code":"calendar.grant_disabled","disposition":"terminal","cause":"Calendar admission is disabled for this app or registration.","remedy":"Ask an operator to enable Calendar admission."},{"code":"calendar.generation_changed","disposition":"terminal","cause":"The grant callback generation changed after the job was admitted.","remedy":"Start a new root read on the current grant."},{"code":"calendar.reconnect_required","disposition":"terminal","cause":"The current Calendar authorization requires reconnection.","remedy":"Reconnect, rediscover, and reselect."},{"code":"calendar.result_expired","disposition":"terminal","cause":"The root traversal expired before this job could publish its result.","remedy":"Start a new root listing or read."},{"code":"calendar.page_expired","disposition":"terminal","cause":"The bounded Calendar page expired before it could be staged.","remedy":"Start a new root listing or read."},{"code":"calendar.page_pending","disposition":"terminal","cause":"The referenced Calendar page is not yet in a completed state.","remedy":"Poll the associated job before fetching the page."},{"code":"calendar.state_unavailable","disposition":"bounded-retryable","cause":"Required Calendar state could not be read or persisted safely.","remedy":"Retry the same signed intent with backoff."},{"code":"calendar.invalid_continuation","disposition":"terminal","cause":"The continuation is malformed or no longer matches its parent page.","remedy":"Start a new root listing or read."},{"code":"calendar.continuation_expired","disposition":"terminal","cause":"The queued resume job references a continuation whose traversal window has expired.","remedy":"Start a new root listing or read."},{"code":"calendar.continuation_not_found","disposition":"terminal","cause":"The queued resume job no longer matches an available parent continuation.","remedy":"Start a new root listing or read."},{"code":"calendar.forbidden","disposition":"terminal","cause":"Google denied access to the requested Calendar resource.","remedy":"Reconnect or choose a readable resource."},{"code":"calendar.not_found","disposition":"terminal","cause":"Google reports that the requested Calendar resource does not exist.","remedy":"Treat the provider resource as unavailable."},{"code":"calendar.unexpected_status","disposition":"terminal","cause":"Google returned a response status outside the supported Calendar contract.","remedy":"Start a new read after operator review."},{"code":"calendar.response_too_large","disposition":"terminal","cause":"The bounded Google Calendar response exceeded the accepted size.","remedy":"Use a smaller new root page size."},{"code":"calendar.malformed_response","disposition":"terminal","cause":"Google returned a Calendar response that failed structural validation.","remedy":"Start a new read after operator review."},{"code":"calendar.rate_limited","disposition":"bounded-retryable","cause":"Calendar execution was refused by local quota or throttled by Google.","remedy":"Retry with bounded backoff."},{"code":"calendar.unavailable","disposition":"bounded-retryable","cause":"Calendar execution or Google Calendar is temporarily unavailable.","remedy":"Retry with bounded backoff."},{"code":"calendar.transport_error","disposition":"bounded-retryable","cause":"The Google Calendar request failed before a valid response arrived.","remedy":"Retry with bounded backoff."},{"code":"calendar.timeout","disposition":"bounded-retryable","cause":"The bounded Google Calendar request exceeded its timeout.","remedy":"Retry with bounded backoff."}]},"ActivityListResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ActivityEvent"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` (with the same filters) for older events. A page may hold fewer events than `limit`, even none, while this is set; keep paging until it is null."}},"required":["events","next_cursor"]},"ActivityEvent":{"type":"object","properties":{"id":{"type":"string","description":"Stable id. An operation keeps one event whose outcome is updated in place; a document event shares its id with the `accounting.document.status_changed` webhook, a connection event with the `connection.*` webhook."},"type":{"type":"string","enum":["operation","document.changed","connection.connected","connection.reconnect_required","connection.disconnected"],"x-ir-enum-open":true,"description":"What happened.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"occurred_at":{"type":"string","description":"ISO-8601 UTC. For an operation, when it was requested (see operation.completed_at); for a document, when the runtime recorded the provider change; for a connection, when its status changed."},"connection_id":{"type":"string"},"provider_key":{"type":"string","description":"For example quickbooks or xero."},"summary":{"type":"string","description":"One customer-safe English sentence, e.g. \"Invoice INV-1 updated in QuickBooks.\" It never carries provider text. Build your own wording from the other fields if you prefer."},"operation":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Neutral operation, e.g. accounting.invoice.update."},"job_id":{"type":"string","description":"Read details with GET /v1/accounting/operations/{job_id}."},"outcome":{"type":"string","enum":["pending","succeeded","failed","resolved","cancelled"],"x-ir-enum-open":true,"description":"Current outcome of the operation: pending (not finished), succeeded (written and verified), failed, resolved (support marked it resolved; it does not prove the write happened), cancelled.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"completed_at":{"type":["string","null"]}},"required":["name","job_id","outcome","completed_at"]},"document":{"type":["object","null"],"properties":{"type":{"type":"string","description":"invoice, payment, credit_application, customer…"},"erp_id":{"type":"string"},"provider_id":{"type":["string","null"]},"status":{"type":["string","null"],"description":"Provider status for a document.changed event, e.g. open, partially_paid, paid, voided, deleted. Null on an operation event."}},"required":["type","erp_id","provider_id","status"]},"connection":{"type":["object","null"],"properties":{"status":{"type":"string"},"previous_status":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["status","previous_status","reason"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Neutral accounting error code, the same one GET /v1/accounting/operations/{job_id} returns."},"message":{"type":"string","description":"Customer-safe text for this code."},"reason":{"type":["string","null"],"enum":["provider_unsupported","not_offered_yet","not_enabled_for_app","disabled","disabled_for_tenant","disabled_for_connection","misconfigured","reconnect_required","unavailable",null],"x-ir-enum-open":true,"description":"Why it is not available: provider_unsupported (the provider has no such operation or behaviour; see alternative), not_offered_yet (the runtime does not offer it yet), not_enabled_for_app, disabled (off for every tenant), disabled_for_tenant (this tenant's Kill or Disarm), disabled_for_connection (the connection's settings turn the record type off, or an exact per-connection case is not granted), misconfigured (ask support; retrying does not help), reconnect_required (the connection was consented before the operation needed a scope it now needs; reconnect it, then read again), unavailable (could not be determined; read again later). Treat an unknown reason as not available.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["code","message","reason"]}},"required":["id","type","occurred_at","connection_id","provider_key","summary","operation","document","connection","error"]},"AvailableProviders":{"type":"object","properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/AvailableProvider"}}},"required":["providers"]},"AvailableProvider":{"type":"object","properties":{"provider_key":{"type":"string","description":"Pass this as `provider_key` to POST /v1/connections/connect-session.","example":"xero"},"display_name":{"type":"string","example":"Xero"},"category":{"type":"string","description":"Which unified API serves this provider: `accounting` (/v1/accounting/*) today; `meetings` and `calendar` as they ship. New categories may appear: treat one you do not recognise as a provider your product does not use yet.","example":"accounting"},"enabled":{"type":"boolean","description":"True when your app is set up for this provider, so you can offer Connect. False means it is not set up for your app yet (contact support). A connect can still be refused with 503 `connect.provider_not_configured` while the runtime operator is still adding this provider's credentials to the environment."}},"required":["provider_key","display_name","category","enabled"]},"SyncJobWithStepsDTO":{"allOf":[{"$ref":"#/components/schemas/SyncJobPublicDTO"},{"type":"object","properties":{"result_status":{"type":"string","enum":["none","available"],"x-ir-enum-open":true,"description":"Whether this job has an explicitly published public result. Results share the job row lifecycle and do not expire independently.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"result":{"$ref":"#/components/schemas/SyncJobResult"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/SyncJobStepPublicDTO"}}},"required":["result_status","result","steps"]}]},"SyncJobResult":{"type":["object","null"],"additionalProperties":{},"description":"Recipe-declared, non-secret JSON result. The UTF-8 JSON representation is limited to 32 KiB. This is never an automatic projection of step output, credentials, or a raw provider response."},"SyncJobStepPublicDTO":{"type":"object","properties":{"id":{"type":"string"},"step_key":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed","skipped"],"x-ir-enum-open":true,"description":"Lifecycle state of the individual recipe step.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"attempt_count":{"type":"integer","minimum":0},"error_code":{"$ref":"#/components/schemas/SyncJobFailureCode"},"provider_status_code":{"type":["integer","null"]},"provider_request_id":{"type":["string","null"]},"started_at":{"type":["integer","null"]},"completed_at":{"type":["integer","null"]}},"required":["id","step_key","status","attempt_count","error_code","provider_status_code","provider_request_id","started_at","completed_at"]},"SyncJobReplayResult":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued"],"x-ir-enum-open":true,"description":"Publication acknowledgement for the replay request, not the current job status; poll the job for execution status.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}},"required":["job_id","status"]},"SyncJobReplayRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}}}},"parameters":{}},"paths":{"/v1/health":{"get":{"tags":["Health"],"summary":"Liveness probe.","operationId":"getHealth","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"example":"ok","x-ir-enum-open":true,"description":"Liveness state.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"version":{"type":"string","example":"0.1.0"}},"required":["status","version"]}}}}}}},"/v1/tenants":{"post":{"tags":["Tenants"],"operationId":"registerTenant","summary":"Register or recover one product customer mapping.","description":"The active authenticated app is the owner; the product backend must authorize its customer administrator. Atomic exact app/external-ID registration converges under concurrent calls and lost responses. Existing IDs and metadata win. Inactive mappings return 409 without reactivation. Retain mappings/tombstones and never recycle external IDs; full customer erasure/offboarding is not implemented here. This creates no provider connection and enables no financial operation. Retry with the same external ID and a fresh HMAC nonce/timestamp.","parameters":[{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterTenantRequest"}}}},"responses":{"200":{"description":"Existing active mapping; stored metadata wins","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterTenantResponse"}}}},"201":{"description":"New active mapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterTenantResponse"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC authentication failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"App key IP policy denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"tenant.not_active: retained customer cannot be registered or reactivated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"tenant.registry_unavailable: retry or recover using the same exact external ID and a fresh signature","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/tenants/by-external-id/{external_tenant_id}":{"get":{"tags":["Tenants"],"operationId":"getTenantByExternalId","summary":"Recover one owned customer mapping by exact external ID.","description":"App identity comes only from HMAC authentication. No customer collection is exposed. Inactive retained mappings remain readable; their existence grants no consent or financial authority. IDs are exact and case-sensitive. The product backend owns authorization of its customers.","parameters":[{"schema":{"type":"string","pattern":"^(?:[A-Za-z0-9._-]{1,128}|%2E(?:%2E)?)$","description":"Exact external customer ID. For dot-only IDs use %252E for '.' or %252E%252E for '..' in the URL path to avoid URL dot-segment normalization."},"required":true,"description":"Exact external customer ID. For dot-only IDs use %252E for '.' or %252E%252E for '..' in the URL path to avoid URL dot-segment normalization.","name":"external_tenant_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Owned mapping, including retained inactive status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantMapping"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC authentication failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"App key IP policy denied","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"tenant.not_found: no mapping in the authenticated app","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"tenant.registry_unavailable: retry or recover using the same exact external ID and a fresh signature","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/connect-session":{"post":{"tags":["Connections"],"summary":"Begin a tenant connect flow for a provider.","operationId":"createConnectSession","parameters":[{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectSessionRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectSessionResponse"}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Provider not enabled, tenant mismatch, or authz.tenant_inactive","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Connection OAuth lifecycle is busy, QuickBooks consent is frozen, or accounting.connection_exists (another accounting provider is connected)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"connect.provider_not_configured: the runtime is not configured for this provider in this environment","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections":{"get":{"tags":["Connections"],"summary":"List connections for the requesting tenant.","description":"Returns a deterministic, bounded page of authoritative connection lifecycle state derived from the administrative app state, confirmed native projection generation and scoped token-vault state. The public response is an explicit allowlist and never includes credentials, OAuth state, granted scopes, vault metadata or operator-only fields.","operationId":"listConnections","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2048},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Tenant-scoped connection page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionsListResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}/disconnect":{"post":{"tags":["Connections"],"summary":"Disconnect one native accounting connection.","operationId":"disconnectConnection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectConnectionRequest"}}}},"responses":{"204":{"description":"Disconnected, or the same request already completed. QuickBooks revokes the grant. Xero removes only this organisation's Xero connection for the connecting user and never revokes a Xero token. A Xero disconnect that could not reach Xero (the grant is dead) completes locally and carries `X-IR-Provider-Cleanup: customer_action_required`: the Xero user who connected the organisation can remove it at https://apps.xero.com/connected.","headers":{"X-IR-Provider-Cleanup":{"description":"Present only on a Xero disconnect that completed locally without removing the Xero connection (`customer_action_required`), and on its same-key replay. Never sent for QuickBooks.","schema":{"type":"string","enum":["customer_action_required"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."}}}},"400":{"description":"Request validation failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Connection or company identity not found in the authenticated scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"`oauth.lifecycle_busy`: a different OAuth lifecycle operation owns the connection. `connection.recovery_pending` (Xero only): unresolved financial writes exist on a live Xero connection; the body carries counts per kind only. Retry the same key after operator recovery, or later once the sweeper has flagged the writes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Provider release (QuickBooks revoke, Xero organisation removal) or local projection must be retried","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/oauth/callback":{"get":{"tags":["Connections"],"summary":"Provider → runtime callback for the native OAuth flow.","operationId":"oauthCallback","security":[],"parameters":[{"schema":{"type":"string"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"realmId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"error","in":"query"}],"responses":{"302":{"description":"Redirect to product app return_url."},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"Unknown / expired / completed session (uniform, no enumeration).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}":{"get":{"tags":["Connections"],"summary":"Fetch authoritative status for one connection.","description":"Use this response, rather than an OAuth callback query hint, as the authoritative connection state. A stale connected app projection is demoted when its native callback generation is unconfirmed or the scoped token vault is terminal or missing. Unknown and out-of-scope connection ids return the same non-enumerating response.","operationId":"getConnection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Tenant-scoped connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionPublicDTO"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Connection not found in this app and tenant scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}/quickbooks/status/{entity_type}/{external_id}":{"get":{"tags":["QuickBooks"],"operationId":"getQuickBooksTransactionStatus","summary":"Read scoped QuickBooks transaction status","description":"Reads the last authoritative projection. refresh=1 performs quota-controlled provider GET reads and may update local status/outbound notifications. This endpoint never performs a financial write or grants financial operation admission. Balances use two-decimal minor units; unsupported currencies fail closed.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["Invoice","Payment"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity_type","in":"path"},{"schema":{"type":"string","pattern":"^[0-9]{1,32}$"},"required":true,"name":"external_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","enum":["0","1"]},"required":false,"name":"refresh","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Provider/company-bound status projection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuickBooksStatusResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Scoped connection or status not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Connection or status refresh unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Authoritative read unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}/quickbooks/recovery":{"get":{"tags":["QuickBooks"],"operationId":"getQuickBooksRecovery","summary":"Inspect scoped QuickBooks recovery work","description":"Reads persisted current-company/current-generation status and pending work. Delivery states are a sample for the latest100 scoped outbox events. This endpoint performs no provider call and does not claim fanout is delivered.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Confirmed native binding and durable work","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"recovery":{"type":"object","properties":{"binding":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"provider_account_id":{"type":"string"},"callback_epoch":{"type":"integer","minimum":0}},"required":["app_id","tenant_id","connection_id","provider_account_id","callback_epoch"]},"summary":{"type":"object","properties":{"known_transactions":{"type":"integer","minimum":0},"pending_refreshes":{"type":"integer","minimum":0},"pending_outbox":{"type":"integer","minimum":0},"delivery_states":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"delivery_sample_events":{"type":"integer","minimum":0},"recent_failures":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string"},"external_id":{"type":"string"},"reason":{"type":"string"},"occurred_at":{"type":"number"}},"required":["entity_type","external_id","reason","occurred_at"]}}},"required":["known_transactions","pending_refreshes","pending_outbox","delivery_states","delivery_sample_events","recent_failures"]}},"required":["binding","summary"]}},"required":["app_id","tenant_id","recovery"]}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Native company, generation or cursor unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"tags":["QuickBooks"],"operationId":"recoverQuickBooksStatus","summary":"Explicitly refresh a bounded page of persisted QuickBooks identities","description":"Performs controlled accounting GETs only: up to20 transaction targets and64 accounting GET attempts (default32). OAuth maintenance is separate. Dependencies are durable; a failed target leaves cursor progress unchanged. The authenticated cursor binds app, tenant, company and connection generation. This operation never replays a financial POST, changes a financial request key or marks a webhook delivered. Terminal deleted projections are retained without inventing a new deletion from404.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"expected_provider_account_id":{"type":"string","pattern":"^\\d{1,32}$"},"expected_callback_epoch":{"type":"integer","minimum":0},"max_transactions":{"type":"integer","minimum":1,"maximum":20},"max_provider_gets":{"type":"integer","minimum":1,"maximum":64},"cursor":{"type":"string","minLength":1,"maxLength":4096}},"required":["tenant_id","expected_provider_account_id","expected_callback_epoch"],"additionalProperties":false}}}},"responses":{"200":{"description":"Actual applied projections, accounting GET count, fanout inserts and durable remaining work","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"recovery":{"type":"object","properties":{"binding":{"type":"object","properties":{"app_id":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"provider_account_id":{"type":"string"},"callback_epoch":{"type":"integer","minimum":0}},"required":["app_id","tenant_id","connection_id","provider_account_id","callback_epoch"]},"outcome":{"type":"string","enum":["complete","more","blocked","get_budget_exhausted"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"applied":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["Invoice","Payment"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"external_id":{"type":"string"},"projection_revision":{"type":"integer","exclusiveMinimum":0},"changed":{"type":"boolean"}},"required":["entity_type","external_id","projection_revision","changed"]}},"provider_get_attempts":{"type":"integer","minimum":0},"provider_get_count_confirmed":{"type":"boolean"},"fanout_deliveries_created":{"type":"integer","minimum":0},"cursor":{"type":"string"},"failure":{"type":["object","null"],"properties":{"code":{"type":"string"},"target":{"type":["object","null"],"properties":{"entity_type":{"type":"string","enum":["Invoice","Payment"],"x-ir-enum-open":true,"description":"**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description."},"external_id":{"type":"string"}},"required":["entity_type","external_id"]}},"required":["code","target"]},"summary":{"type":"object","properties":{"known_transactions":{"type":"integer","minimum":0},"pending_refreshes":{"type":"integer","minimum":0},"pending_outbox":{"type":"integer","minimum":0},"delivery_states":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"delivery_sample_events":{"type":"integer","minimum":0},"recent_failures":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string"},"external_id":{"type":"string"},"reason":{"type":"string"},"occurred_at":{"type":"number"}},"required":["entity_type","external_id","reason","occurred_at"]}}},"required":["known_transactions","pending_refreshes","pending_outbox","delivery_states","delivery_sample_events","recent_failures"]}},"required":["binding","outcome","applied","provider_get_attempts","provider_get_count_confirmed","fanout_deliveries_created","cursor","failure","summary"]}},"required":["app_id","tenant_id","recovery"]}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Native company, generation or cursor unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}/quickbooks/master/{entity}":{"get":{"tags":["QuickBooks"],"operationId":"lookupQuickBooksMasterData","summary":"Read exact current master data, including inactive state","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["Customer","Item","TaxCode","TaxRate"],"x-ir-enum-open":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,32}$"},"required":false,"name":"external_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Authoritative company-bound record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuickBooksMasterRecord"}}}},"400":{"description":"Invalid master request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Scoped mapping/record not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Master binding unconfirmed or conflicting","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Provider read unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/connections/{id}/quickbooks/master/mappings/{entity}/{erp_id}":{"get":{"tags":["QuickBooks"],"operationId":"getQuickBooksMasterMapping","summary":"Read or refresh stable ERP master mapping","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["Customer","Item","TaxCode","TaxRate"],"x-ir-enum-open":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","enum":["0","1"]},"required":false,"name":"refresh","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Stable mapping and drift/inactive state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuickBooksMasterMapping"}}}},"400":{"description":"Invalid master request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Scoped mapping/record not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Master binding unconfirmed or conflicting","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Provider read unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"tags":["QuickBooks"],"operationId":"bindQuickBooksMasterMapping","summary":"Explicitly bind verified provider master or reconcile an uncertain command","description":"Performs controlled GET reads and local mapping updates only. The chosen provider id must match current company and any pending command's frozen fields. TaxCode/TaxRate are read-only; no reactivation or tax-rate invention.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["Customer","Item","TaxCode","TaxRate"],"x-ir-enum-open":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Supported master entity; tax entities have no write operation.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"expected_company_id":{"type":"string","pattern":"^\\d{1,32}$"},"external_id":{"type":"string","pattern":"^\\d{1,32}$"},"reconcile_command_id":{"type":"string","minLength":1,"maxLength":128}},"required":["tenant_id","expected_company_id","external_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Provider-verified local binding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuickBooksMasterRecord"}}}},"400":{"description":"Invalid master request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Scoped mapping/record not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Master binding unconfirmed or conflicting","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Provider read unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/calendar/grants/{grant_id}/resources":{"get":{"tags":["Calendar"],"summary":"List selected Calendar resources.","description":"Returns only local selected-resource metadata for the grant's current callback epoch. This route performs no provider request and remains available when read admission is disabled.","operationId":"listCalendarResources","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"grant_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2048},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Current tenant-scoped selected Calendar resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarResourcesListResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant or persisted grant binding denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Calendar grant not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Calendar state is unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"tags":["Calendar"],"summary":"Select one discovered Calendar resource.","description":"Creates a local selected-resource binding from a recent completed discovery page. This endpoint performs no provider request or token refresh.","operationId":"selectCalendarResource","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"grant_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectCalendarResourceRequest"}}}},"responses":{"200":{"description":"Selected Calendar resource, including an exact idempotent retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarResource"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Provider, event-read scope or discovery proof denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Calendar grant or discovery page not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Selection identity, lifecycle or discovery publication is not current.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"The discovery proof expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Calendar state is unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/calendar/grants/{grant_id}":{"get":{"tags":["Calendar"],"summary":"Fetch scoped Calendar grant status.","description":"Returns persisted grant identity, lifecycle status and current read capability without decrypting credentials or requiring Calendar admission to be enabled.","operationId":"getCalendarGrant","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"grant_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Tenant-scoped Calendar grant status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarGrant"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant or persisted grant binding denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Calendar grant not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Calendar state is unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/calendar/grants/{grant_id}/revoke":{"post":{"tags":["Calendar"],"summary":"Revoke one Calendar grant.","description":"Establishes local denial and runs the grant-scoped native OAuth revocation journal. It remains reachable when Calendar read admission is disabled and never refreshes a token to offboard.","operationId":"revokeCalendarGrant","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"grant_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarRevokeRequest"}}}},"responses":{"204":{"description":"Grant revoked, or the same revoke intent already completed."},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant scope denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Calendar grant not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"A different OAuth lifecycle operation owns the grant.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Provider revocation or local projection must be retried.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/calendar/resources/{resource_id}/detach":{"post":{"tags":["Calendar"],"summary":"Detach one selected Calendar resource.","description":"Tombstones only the scoped local resource binding. It does not refresh credentials, call Google, revoke the grant or affect sibling resources, and remains available when read admission is disabled.","operationId":"detachCalendarResource","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"resource_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarDetachRequest"}}}},"responses":{"204":{"description":"Resource detached, or the same detach intent already completed."},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant or persisted resource binding denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Calendar resource not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"The resource generation or detach intent changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Calendar state is unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/calendar/pages/{page_id}":{"get":{"tags":["Calendar"],"summary":"Fetch one immutable Calendar result page.","description":"Returns the exact bounded page bytes while the originating grant/resource binding remains current and the root traversal is unexpired. This endpoint performs no provider request or token refresh.","operationId":"getCalendarPage","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"required":true,"name":"page_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Immutable Calendar page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarPublicPage"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Current grant or selected-resource authorization denied.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Page not found in this app and tenant scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Grant generation changed or the page job is not completed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"The scoped page expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Calendar state is temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/mappings/{sync_profile_id}/dry-run":{"post":{"tags":["Mappings"],"summary":"Preview the provider payload a sync_profile would build for a sample input.","operationId":"dryRunMapping","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sync_profile_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingDryRunRequest"}}}},"responses":{"200":{"description":"Dry-run result (no provider write, no D1 write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MappingDryRunResult"}}}},"400":{"description":"Bad request (unknown object_type, malformed body, etc).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Provider not enabled or tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"sync_profile not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/operations/execute":{"post":{"tags":["Operations"],"summary":"Enqueue a provider operation (sync recipe) for execution.","description":"QuickBooks Invoice CREATE uses erp.quickbooks.invoice.created v4 with existing native CustomerRef, ItemRef and TaxCodeRef values, TaxExcluded calculation and tax_declarations; historical v3 jobs remain replayable. v6 adds a duplicate-DocNumber check and a closing-date check inside the connection's serialized slot before any reservation (one extra provider GET when DocNumber is set); the neutral accounting API uses v6. CREATE rejects root customer/items and Invoice Id/SyncToken/sparse fields. Invoice UPDATE uses erp.quickbooks.invoice.updated v1, object_type invoice_update, an explicit immutable idempotency_key and ERP change ID, original_invoice company/Invoice/customer/CAD/tax evidence, and a sparse Invoice with the original Id and SyncToken. UPDATE retains every existing SalesItem line ID, ItemRef and TaxCodeRef exactly once and requires an open unpaid sale without payment or credit activity. For a taxable amount change on one existing line, the runtime derives a complete TxnTaxDetail from verified native rates and freezes the resulting provider body; callers still cannot send TxnTaxDetail. Native financial writes require current same-app policy qualification and global enablement. New tenants inherit app qualification without an Arm step; explicit tenant Kill/Disarm overrides and emergency aborts still refuse writes. Google Calendar payloads use the standalone CalendarDiscoveryInitialPayload, CalendarDiscoveryResumePayload, CalendarEventsInitialPayload, and CalendarEventsResumePayload schemas published in components.schemas.","operationId":"executeOperation","parameters":[{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationsExecuteRequest"}}}},"responses":{"202":{"description":"Accepted; job enqueued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationsExecuteResult"}}}},"400":{"description":"Invalid request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Provider/tenant not authorized, or operation not enabled.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Recipe not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Recipe version retired, or idempotency identity conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"The Calendar continuation expired and a new root read is required.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"tenant_enablement_unavailable — the per-tenant enablement read FAILED, so the runtime could not evaluate the rollout gate and refused rather than guess. Distinct from the 403: that one is a decision, this one is the absence of one. No `Retry-After` is sent, and the nonce for this request is already consumed — retry with a freshly signed request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/providers":{"get":{"tags":["Accounting"],"operationId":"listAccountingProviders","summary":"List accounting providers, their capabilities and required mapping kinds","description":"Provider-neutral. Build the ERP's Connect and mapping screens from this data so a new accounting provider needs no ERP change.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Providers and the tenant's accounting connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingProviders"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection, mapping or provider reference not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the reference is unusable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/reference-data/{kind}":{"get":{"tags":["Accounting"],"operationId":"lookupAccountingReference","summary":"Look up one provider reference by provider id or exact name","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","payment_method","deposit_account","refund_account","income_account"],"x-ir-enum-open":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"kind","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"required":false,"name":"provider_ref","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Provider-verified reference in neutral shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingReference"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection, mapping or provider reference not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the reference is unusable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/reference-data/{kind}/options":{"get":{"tags":["Accounting"],"operationId":"listAccountingReferenceOptions","summary":"Page through the provider records a mapping kind can point at","description":"For an ERP mapping dropdown, for example payment methods or deposit accounts. Only records the write path accepts for the kind are listed (accounts are filtered by type). Accounts carry `account_type` and `account_code`; the usual picks (a bank account, or QuickBooks Undeposited Funds, for deposits and refunds) carry `recommended: true` and come first (on QuickBooks, first within each page). Any listed record maps. Inactive records are included with `usable: false`; map only usable ones. The cursor is bound to the connection's company and the kind.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["payment_method","deposit_account","refund_account","income_account"],"x-ir-enum-open":true,"description":"Neutral code mapping kind. Customers, items and tax codes are listed by records/{entity}; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Neutral code mapping kind. Customers, items and tax codes are listed by records/{entity}; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"kind","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingReferenceOptionPage"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a snapshot pull is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Too many records for a live match, or no snapshots for this provider or type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/mappings/{kind}/{erp_code}":{"get":{"tags":["Accounting"],"operationId":"getAccountingMapping","summary":"Read one ERP-to-provider mapping","description":"A code mapping (payment_method, deposit_account, refund_account, income_account) is verified against the provider with one read through the connection's coordinator: `state` is `inactive` when the provider record is archived or inactive, and `drifted` when it is gone or no longer usable for the kind (for example an account whose type changed). When that read cannot be confirmed (rate limit, provider unavailable), the stored state is returned. Customer, item and tax code mappings return their stored state.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","payment_method","deposit_account","refund_account","income_account"],"x-ir-enum-open":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"kind","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_code","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Mapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingMapping"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection, mapping or provider reference not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the reference is unusable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"put":{"tags":["Accounting"],"operationId":"setAccountingMapping","summary":"Map an ERP record or code to a provider-verified reference","description":"The provider reference is read through the connection's coordinator before it is stored. `treatment` is required for tax_code and refused otherwise.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","payment_method","deposit_account","refund_account","income_account"],"x-ir-enum-open":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"kind","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_code","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"provider_ref":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"treatment":{"type":"string","enum":["taxable","zero_rated","exempt","not_applicable"],"x-ir-enum-open":true,"description":"ERP tax treatment of a tax code.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."}},"required":["tenant_id","provider_ref"],"additionalProperties":false}}}},"responses":{"200":{"description":"Stored mapping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingMapping"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection, mapping or provider reference not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the reference is unusable. A PUT for a customer, item or tax code whose ERP code is already bound to a different provider record re-binds it, the same on every provider; it answers a retryable pending_change while a create or update of that ERP record, or another change of its mapping, runs. A refusal carries `reason` (bound_to_other_record with `bound_erp_id`, not_usable_for_kind, inactive, ambiguous; the legacy record_already_bound is no longer returned), the same on every provider, and `detail` says what to do. The passing causes pending_change and connection_changed come as a retryable 503 accounting.provider_unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"delete":{"tags":["Accounting"],"operationId":"deleteAccountingMapping","summary":"Remove a code mapping","description":"Customer and item mappings are company-bound master links and cannot be deleted; rebind them instead. Deleting a tax_code mapping removes its treatment and its binding to the provider tax code or rate, so that provider record can be mapped to another ERP code; it also removes a binding left without a treatment.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","payment_method","deposit_account","refund_account","income_account"],"x-ir-enum-open":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Neutral mapping kind. Read the provider's mapping_kinds for the kinds it needs; new kinds may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"kind","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_code","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"204":{"description":"Removed"},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection, mapping or provider reference not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the reference is unusable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/settings":{"get":{"tags":["Accounting"],"operationId":"getAccountingSettings","summary":"Read the connection's sync settings","description":"Created on first use from the tenant-local date sent with the connect session, and reset when the connection is rebound to a different provider company.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingSettings"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the settings changed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"App quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"put":{"tags":["Accounting"],"operationId":"setAccountingSettings","summary":"Choose which record types the connection syncs, and from which day","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"record_types":{"type":"array","items":{"type":"string","enum":["invoice","payment","credit_memo","refund"],"x-ir-enum-open":true,"description":"Neutral record type a connection can sync; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"maxItems":4,"description":"Omitted keeps the current record types."},"sync_start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"New first day to sync, YYYY-MM-DD, at most tomorrow (UTC). Omitted keeps the current date. Moving it earlier lets older documents through: match or link the provider's existing records of that period first, or they may be written twice. Moving it later also refuses later new payments, refunds and credits created (or, without erp_created_at, dated) before the new day; updates, voids and deletes of linked documents are not affected."},"expected_revision":{"type":"integer","exclusiveMinimum":0}},"required":["tenant_id","expected_revision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Stored settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingSettings"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the settings changed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"App quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/capabilities":{"get":{"tags":["Accounting"],"operationId":"getAccountingConnectionCapabilities","summary":"What this connection supports now, in provider-neutral names","description":"Every neutral operation with whether it passes admission for this tenant now (catalog enablement, the tenant's Kill or Disarm, the kill switch, the connection's record types), and provider-neutral feature flags. Show or hide actions from this instead of the provider name. Advisory: request-specific checks (sync start date, closed period, mappings, revisions, tax, company currency) still run on every write. Read it again after a connect or reconnect.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Capabilities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingConnectionCapabilities"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"App quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}":{"get":{"tags":["Accounting"],"operationId":"listAccountingRecords","summary":"Page through the provider's customers, items, tax codes or a customer's open credits","description":"Prepayments: `customer` (an ERP customer id bound to a provider customer) is required, and only that customer's open credits are listed, read live: on QuickBooks payments with unapplied credit, on Xero receive overpayments with remaining credit (Xero prepayments are not listed); each carries `open_amount` and `bound_erp_id`; a page may hold fewer than `limit` rows, so follow `next_cursor`, which is bound to the customer. Inactive records are included, with `usable: false`. Active tax codes are sales codes only (the only ones a binding accepts), each with its `rate_percent` and `suggested_treatment` (`taxable` above 0; `exempt` or `zero_rated` at 0 when the provider marks it; else null; a hint only, a bind takes the treatment you send); inactive codes are listed with `usable: false` and `rate_percent: null`; on QuickBooks a page of tax codes may hold fewer than `limit` rows, so follow `next_cursor`. The cursor is bound to the connection's company and the entity; it is not stable while records are added during a scan. From a snapshot, records are in name order and show no email or SKU.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","prepayment"],"x-ir-enum-open":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["auto","snapshot","live"],"x-ir-enum-open":true,"description":"auto: a ready snapshot under 24 hours old, else live (409 while a pull runs); snapshot: a ready snapshot only; live: the provider. Match defaults to auto; list defaults to live, or snapshot when `q` is given, and a cursor keeps its source.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":false,"description":"auto: a ready snapshot under 24 hours old, else live (409 while a pull runs); snapshot: a ready snapshot only; live: the provider. Match defaults to auto; list defaults to live, or snapshot when `q` is given, and a cursor keeps its source.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"source","in":"query"},{"schema":{"type":"string","minLength":3,"maxLength":254,"description":"Search a ready snapshot (customers and items): on customers an exact email when it contains @; otherwise a name prefix (trimmed, case-folded)."},"required":false,"description":"Search a ready snapshot (customers and items): on customers an exact email when it contains @; otherwise a name prefix (trimmed, case-folded).","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Prepayments only, and required there: the ERP customer id whose open credits to list. It must be bound to a provider customer (409 accounting.mapping_missing otherwise)."},"required":false,"description":"Prepayments only, and required there: the ERP customer id whose open credits to list. It must be bound to a provider customer (409 accounting.mapping_missing otherwise).","name":"customer","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordPage"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found, or no ready snapshot for source=snapshot","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a snapshot pull is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Too many records for a live match, or no snapshots for this provider or type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/match":{"post":{"tags":["Accounting"],"operationId":"matchAccountingRecords","summary":"Find exact provider matches for ERP records (100 live, 1,000 from a snapshot)","description":"Prepayments: each record needs `customer` (and may send `amount`); the candidates are that customer's open credits, read live, at most 25 records per call; a prepayment is never `matched`, only `suggested` (a person confirms which credit is the opening balance). Customers match on email, then name; items on SKU, then name; tax codes on name (a tax code with no name match and a `rate_percent` is offered the active sales tax codes with that rate, as `suggested`). Exact means equal after trimming and case-folding. `matched` needs exactly one active record on the primary key that is usable (`usable` is not false) and not bound to another ERP id. A customer with no email, or an item with no SKU, is also `matched` (`matched_on: name`) on exactly one such record with an equal name where the provider enforces unique names: QuickBooks customers and items, Xero contacts. Two records of one request never both match one provider record: both come back `suggested` with `not_matched_reason: shared_with_other_record`. Anything else with candidates is `suggested`; each candidate's `match_reasons` says why it was offered. Names equal once punctuation and spacing are ignored (\"ABC Ltd.\" and \"abc  ltd\") and a customer's `tax_number` or `account_number` only ever suggest. A provider email field holding several addresses (QuickBooks allows `a@x.com, b@y.com`) equals each of them, and the whole field, as an email key. Loose names are compared against a snapshot and against tax codes (the whole list is read); a live customer or item match finds rows by exact keys only. Nothing is bound. With a ready record snapshot (customers and items) the match reads the snapshot, not the provider: up to 1,000 records per call, candidates show no email or SKU, and the response names the source.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","prepayment"],"x-ir-enum-open":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"records":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","minLength":1,"maxLength":254},"sku":{"type":"string","minLength":1,"maxLength":100},"tax_number":{"type":"string","minLength":1,"maxLength":50,"description":"Customers only: the ERP's tax or business number. Compared ignoring case, spaces, dashes, dots and slashes; a hit is only ever `suggested` (`match_reasons: tax_number`). Xero compares it from a snapshot only; QuickBooks has no such field. Where it cannot be compared it is listed in `unsupported_keys`. Ignored elsewhere."},"account_number":{"type":"string","minLength":1,"maxLength":50,"description":"Customers only: the ERP's account number for the customer (Xero AccountNumber). Compared trimmed and case-folded; a hit is only ever `suggested` (`match_reasons: account_number`). QuickBooks has no such field, so it is listed in `unsupported_keys` there. Ignored elsewhere."},"rate_percent":{"type":"string","pattern":"^\\d{1,3}(\\.\\d{1,4})?$","description":"Tax codes only: the ERP rate, e.g. `5` or `14.975`. A tax code whose name matches nothing is offered the provider's active sales tax codes with the same effective rate (on QuickBooks, the sum of a code's sales rates). Ignored elsewhere."},"customer":{"type":"string","minLength":1,"maxLength":128,"description":"Prepayments only, and required there: the ERP customer id (bound to a provider customer) whose open credits are the candidates."},"amount":{"type":"string","pattern":"^\\d{1,13}(\\.\\d{1,2})?$","description":"Prepayments only: the opening balance the ERP holds, e.g. `250.00`. When sent, only credits whose open amount equals it are offered (`match_reasons: amount`)."}},"required":["erp_id","name"],"additionalProperties":false},"minItems":1,"maxItems":1000},"source":{"type":"string","enum":["auto","snapshot","live"],"x-ir-enum-open":true,"description":"auto: a ready snapshot under 24 hours old, else live (409 while a pull runs); snapshot: a ready snapshot only; live: the provider. Match defaults to auto; list defaults to live, or snapshot when `q` is given, and a cursor keeps its source.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."}},"required":["tenant_id","records"],"additionalProperties":false}}}},"responses":{"200":{"description":"One result per ERP record, in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordMatch"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found, or no ready snapshot for source=snapshot","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a snapshot pull is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Too many records for a live match, or no snapshots for this provider or type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/bind":{"post":{"tags":["Accounting"],"operationId":"bindAccountingRecords","summary":"Bind up to 25 confirmed ERP-to-provider pairs","description":"Each row is verified through the provider and stored like PUT /mappings, and succeeds or fails on its own. Prepayment rows need `customer` (the ERP customer id) and bind a customer credit entered in the provider to the ERP prepayment id: the credit is read fresh on the connection's company and must belong to that customer, be in CAD and have open credit, and must not be held by another ERP id; the provider is only read, never written. accounting.prepayment.apply and unapply then work against it as against a prepayment the runtime created (refund and void are not offered yet); `prepayment.origin` says which it is. While a write on the connection that may hold a credit is not settled, a prepayment row is refused with `pending_change`, and so is a re-bind while an apply or unapply of the ERP id is queued or running. A credit whose currency the provider did not report is refused with `currency_unknown`. An ERP id whose own accounting.prepayment.create failed is refused with `create_failed`: bind the credit under a new erp_id. accounting.prepayment.create of a bound ERP id is refused with 409 accounting.document_exists. After a rate-limited row the rest are not attempted; bound rows are never rolled back. tax_code rows need `treatment`. A provider_ref that appears in more than one row is refused with 400 before anything is bound; `errors` names each repeat.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code","prepayment"],"x-ir-enum-open":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Provider record type: customer, item, tax_code, or prepayment (a customer's open credit); new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"bindings":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"provider_ref":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"},"treatment":{"type":"string","enum":["taxable","zero_rated","exempt","not_applicable"],"x-ir-enum-open":true,"description":"ERP tax treatment of a tax code.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"customer":{"type":"string","minLength":1,"maxLength":128,"description":"Prepayment rows only, and required there: the ERP customer id the credit must belong to."}},"required":["erp_id","provider_ref"],"additionalProperties":false},"minItems":1,"maxItems":25}},"required":["tenant_id","bindings"],"additionalProperties":false}}}},"responses":{"200":{"description":"One result per row, in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordBind"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a snapshot pull is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Too many records for a live match, or no snapshots for this provider or type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/snapshots":{"post":{"tags":["Accounting"],"operationId":"startAccountingRecordSnapshot","summary":"Start a background snapshot of every provider customer or item","description":"Returns a running snapshot if one exists, or a ready unexpired one (200) unless `refresh` is true. Otherwise starts a background job (202). A refresh is allowed once per 15 minutes per connection and record type. The job's `sync_job.completed` webhook fires when the snapshot is ready.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item"],"x-ir-enum-open":true,"description":"Record type to snapshot; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Record type to snapshot; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"refresh":{"type":"boolean"}},"required":["tenant_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"A ready, unexpired snapshot already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordSnapshot"}}}},"202":{"description":"A snapshot is being taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordSnapshot"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection or snapshot not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a refresh too soon","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Snapshots are not available for this provider or record type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable, or snapshot capacity reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/snapshots/latest":{"get":{"tags":["Accounting"],"operationId":"getLatestAccountingRecordSnapshot","summary":"The latest snapshot for this connection and record type","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item"],"x-ir-enum-open":true,"description":"Record type to snapshot; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Record type to snapshot; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The latest snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingRecordSnapshot"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection or snapshot not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a refresh too soon","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Snapshots are not available for this provider or record type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable, or snapshot capacity reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/bind-jobs":{"post":{"tags":["Accounting"],"operationId":"startAccountingBindJob","summary":"Bind up to 5,000 confirmed ERP-to-provider customer or item pairs in the background","description":"Starts a background job (202) that verifies every row through the provider, in batches of up to 100, and stores it like the bind route. Each row succeeds or fails on its own; bound rows are never rolled back. One bind job runs per connection at a time. The job's `sync_job.completed` webhook fires when it ends; read the results with GET .../bind-jobs/{job_id}/results. More than 5,000 rows is refused with 413; a provider_ref that appears in more than one row is refused with 400, naming each repeat in `errors`. Keep the request body under 1 MiB.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code"],"x-ir-enum-open":true,"description":"Record type; bind jobs cover customer and item.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Record type; bind jobs cover customer and item.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","minLength":1},"bindings":{"type":"array","items":{"type":"object","properties":{"erp_id":{"type":"string","minLength":1,"maxLength":128},"provider_ref":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}},"required":["erp_id","provider_ref"],"additionalProperties":false},"minItems":1,"description":"At most 5,000 rows; each erp_id once."}},"required":["tenant_id","bindings"],"additionalProperties":false}}}},"responses":{"202":{"description":"The bind job is running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingBindJob"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized, or bind jobs not enabled","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection or bind job not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a bind job is already running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"More than 5,000 rows, or the request body is too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Bind jobs are not available for this provider or record type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/records/{entity}/bind-jobs/{job_id}/results":{"get":{"tags":["Accounting"],"operationId":"getAccountingBindJobResults","summary":"A bind job's status and one page of its per-row results","description":"Rows come in request order, up to 500 per page. Follow `next_cursor` until it is null. Rows of a running job may still read `not_attempted`. Results are kept 7 days after the job ends.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["customer","item","tax_code"],"x-ir-enum-open":true,"description":"Record type; bind jobs cover customer and item.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Record type; bind jobs cover customer and item.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"entity","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"job_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","maxLength":256},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The bind job and one page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingBindJobResults"}}}},"400":{"description":"Invalid request or cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized, or bind jobs not enabled","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection or bind job not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or a bind job is already running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Bind jobs are not available for this provider or record type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/documents/{document_type}/{erp_id}":{"get":{"tags":["Accounting"],"operationId":"refreshAccountingDocument","summary":"Read a document's current revision, status and balance from the provider","description":"Reads the provider now, through the connection's quota. Covers documents this connection wrote. Never writes to the provider. For an invoice it also returns net_amount, total_tax and tax_lines from this read, so an ERP that has no verified before-state for an older invoice can backfill before.totals.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","payment","prepayment"],"x-ir-enum-open":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"document_type","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Current provider state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingDocumentState"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the document is not linked","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/documents/{document_type}/{erp_id}/link":{"put":{"tags":["Accounting"],"operationId":"linkAccountingDocument","summary":"Link the ERP line ids of an invoice created through quickbooks()","description":"For an invoice the runtime created on this connection before the neutral API. Send every line, either with the provider_line_id from the old result or exactly as it was created; the runtime checks them against its own verified create result and records the line map, so update, refund and credit memo can name the lines. Never reads or writes the provider. Repeating the same link is a no-op.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice"],"x-ir-enum-open":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"document_type","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingDocumentLinkRequest"}}}},"responses":{"200":{"description":"The recorded line map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingDocumentLink"}}}},"400":{"description":"Invalid request, or the lines do not match the verified invoice","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, the invoice was not created by the runtime, a mapping is missing, or it is linked with different lines","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/documents/invoice/{erp_id}/online-link":{"get":{"tags":["Accounting"],"operationId":"readAccountingInvoiceOnlineLink","summary":"Read the customer's online link for an invoice","description":"Reads the provider now, through the connection's quota: QuickBooks InvoiceLink, Xero OnlineInvoiceUrl. Covers invoices this connection wrote. Never writes to the provider. Do not cache the URL for long; read it again before you send it.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The invoice's online link, or null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingInvoiceOnlineLink"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the invoice is not linked","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"The provider no longer has the invoice (deleted there)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/connections/{id}/documents/{document_type}/{erp_id}/pdf":{"get":{"tags":["Accounting"],"operationId":"readAccountingDocumentPdf","summary":"Download the provider's PDF of an invoice or credit memo","description":"Reads the PDF the provider renders now, through the connection's quota: QuickBooks invoice or credit memo PDF, Xero invoice or credit note PDF. Covers documents this connection wrote. Never writes to the provider. At most 4 MiB; a larger PDF is 503 accounting.provider_unavailable.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","credit_memo"],"x-ir-enum-open":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":true,"description":"Document type; new types may be added.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"document_type","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"erp_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The PDF bytes","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"No single active accounting connection, or the document is not linked","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"410":{"description":"The provider no longer has the document (deleted there)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider or app quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed, or the PDF is over 4 MiB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/operations":{"post":{"tags":["Accounting"],"operationId":"submitAccountingOperation","summary":"Submit a provider-neutral accounting write","description":"ERP identifiers only. The runtime resolves the tenant's accounting connection and mappings, then admits the native operation with every native guard. Retry with the same idempotency_key and body after a lost response. Payment and void carry the ERP's last revision and before-state, and are checked against the provider's closing date before admission.","parameters":[{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingOperationRequest"}}}},"responses":{"202":{"description":"Accepted; poll polling_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingOperationAccepted"}}}},"400":{"description":"Invalid request or totals","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Accounting connection not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Mapping missing, tax mismatch, idempotency conflict, no single connection, record type off, dated before the sync start, dated in a closed period (payment and void), or the invoice is not linked; or a prepayment apply whose ERP prepayment was re-bound after it was accepted (reason mapping_changed, with job_id and polling_url)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AccountingOperationConflict"}}}},"422":{"description":"The provider does not support this operation or currency","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Quota or provider rate limit; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Accounting provider unavailable or unconfirmed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/accounting/operations/{job_id}":{"get":{"tags":["Accounting"],"operationId":"getAccountingOperation","summary":"Read a neutral write's status and verified result","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"job_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Status, and the neutral result once verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingOperationStatus"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No neutral operation with this job id for the tenant","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Quota exhausted; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/meetings/providers":{"get":{"tags":["Meetings"],"operationId":"listMeetingProviders","summary":"List meeting providers, their capabilities and the tenant's meeting connections","description":"Every meeting provider the runtime ships, with whether your app can use it and what it supports, plus the tenant's active meeting connections. Connect one with POST /v1/connections/connect-session.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Meeting providers and connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingProviders"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/meetings/operations":{"post":{"tags":["Meetings"],"operationId":"submitMeetingOperation","summary":"Create, update or end a meeting","description":"meeting.create returns a join link; meeting.update changes an active meeting's title, times or access (see updatable_fields); meeting.end ends the meeting. The runtime waits briefly for the provider: 200 when the operation finished (check status and error), otherwise 202 with polling_url. Retry with the same idempotency_key and body after a lost response.","parameters":[{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingOperationRequest"}}}},"responses":{"200":{"description":"The operation finished; read status, error and meeting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingOperationStatus"}}}},"202":{"description":"Accepted and still running; poll polling_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingOperationStatus"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized, or the operation is turned off","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Meeting connection or meeting not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Idempotency conflict, connection not active, external_ref held on another connection, create in progress under another key, the meeting is not active, or another update is in progress","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"The provider does not support this operation, field or access level","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Quota or provider rate limit; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Meeting provider unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/meetings/operations/{job_id}":{"get":{"tags":["Meetings"],"operationId":"getMeetingOperation","summary":"Read a meeting operation","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"job_id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The operation and its meeting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingOperationStatus"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No meeting operation with this job id for the tenant","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/meetings/connections/{id}/meetings/{meeting_ref}":{"get":{"tags":["Meetings"],"operationId":"getMeeting","summary":"Read a meeting","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"meeting_ref","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The meeting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meeting"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No meeting with this ref on this connection for the tenant","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/meetings/connections/{id}/meetings/{meeting_ref}/artifacts":{"get":{"tags":["Meetings"],"operationId":"getMeetingArtifacts","summary":"Read a meeting's recording and transcript links","description":"After a meeting, the links to its recordings and transcripts at the provider, and when each call started and ended. Links only: the runtime never stores or passes on the recording or transcript itself. The provider is asked at most once a minute per meeting; a final answer is never re-read. Check again while status is pending.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"meeting_ref","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"The meeting's artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingArtifacts"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant not authorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No meeting with this ref on this connection for the tenant","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"The meeting is not started (creating or failed), the connection is not active and nothing was read before, or the connection is now another account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Provider rate limit and nothing was read before; honor Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Meeting provider unavailable and nothing was read before","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"operationId":"getUsage","summary":"Read job usage for a tenant of the HMAC-authenticated app.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10080,"default":1440},"required":false,"name":"window_minutes","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Current outcomes of retained jobs created in the bounded window. Not provider HTTP call counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Authentication missing or invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Caller lacks scope or tenant does not belong to the verified app.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"usage.window_too_dense: choose a shorter window. No partial counts returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/sync-jobs":{"get":{"tags":["SyncJobs"],"summary":"List sync jobs for the requesting tenant.","operationId":"listSyncJobs","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"connection_id","in":"query"},{"schema":{"type":"string","enum":["queued","processing","completed","failed","dead_lettered","cancelled","manually_resolved"],"x-ir-enum-open":true,"description":"Lifecycle state of the job.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either."},"required":false,"description":"Lifecycle state of the job.\n\n**Extensible enum.** New members may be added in a MINOR release without a version bump. Clients MUST tolerate values they do not recognise — map an unknown value to an explicit \"unrecognised\" case rather than rejecting the response. See \"Enum stability\" in the API description.\n\nAs a request value, only the members listed here are accepted: the runtime validates this field and returns `400` on anything else. New members may become accepted in a MINOR release, so do not treat this list as permanently fixed — but do not send a value that is not on it either.","name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,16}$","description":"Only jobs that reached a final state at or after this time (Unix epoch milliseconds, inclusive). Use it to catch up after missed webhooks: page through with `cursor` (newest created first), and on the next call pass the largest `completed_at` you saw minus a safety overlap of at least 5 minutes, skipping job ids you already handled. `completed_at` is stamped by the worker just before the job's final write, so jobs can become visible slightly out of order."},"required":false,"description":"Only jobs that reached a final state at or after this time (Unix epoch milliseconds, inclusive). Use it to catch up after missed webhooks: page through with `cursor` (newest created first), and on the next call pass the largest `completed_at` you saw minus a safety overlap of at least 5 minutes, skipping job ids you already handled. `completed_at` is stamped by the worker just before the job's final write, so jobs can become visible slightly out of order.","name":"completed_since","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Sync jobs page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobsListResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/activity":{"get":{"tags":["Activity"],"summary":"List a tenant's integration activity, newest first.","description":"Operations you sent (with their current outcome and a customer-safe failure message), document changes the provider reported, and connection status changes. Built for showing your own customer an integration log.","operationId":"listActivity","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only events of this connection."},"required":false,"description":"Only events of this connection.","name":"connection_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Only events about this ERP document id (your id). Includes operations that settle or reverse an invoice with this id (payments, refunds, credit applications). Connection events are excluded."},"required":false,"description":"Only events about this ERP document id (your id). Includes operations that settle or reverse an invoice with this id (payments, refunds, credit applications). Connection events are excluded.","name":"erp_id","in":"query"},{"schema":{"type":"string","pattern":"^(operation|document|connection)(,(operation|document|connection))*$","description":"Comma-separated event groups: operation, document, connection. Default: all three."},"required":false,"description":"Comma-separated event groups: operation, document, connection. Default: all three.","name":"types","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,16}$","description":"Oldest time to include (Unix epoch milliseconds, inclusive). Default: 90 days before `until`."},"required":false,"description":"Oldest time to include (Unix epoch milliseconds, inclusive). Default: 90 days before `until`.","name":"since","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,16}$","description":"Newest time to include (Unix epoch milliseconds, exclusive). Default: now. `until - since` may be at most 366 days."},"required":false,"description":"Newest time to include (Unix epoch milliseconds, exclusive). Default: now. `until - since` may be at most 366 days.","name":"until","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 50."},"required":false,"description":"Default 50.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Activity page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityListResponse"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/providers":{"get":{"tags":["Providers"],"summary":"List the providers your app can connect, grouped by category.","description":"Every provider the runtime ships, in this environment, with whether your app can connect it. Build your integrations screen from this list so a newly added provider appears without a code change. Then use GET /v1/connections for a tenant's connections.","operationId":"listProviders","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Available providers, ordered by category then provider key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableProviders"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/sync-jobs/{id}":{"get":{"tags":["SyncJobs"],"summary":"Fetch a single sync job with its step timeline.","operationId":"getSyncJob","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"responses":{"200":{"description":"Job with steps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobWithStepsDTO"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Job not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/sync-jobs/{id}/replay":{"post":{"tags":["SyncJobs"],"summary":"Replay a failed/dead-lettered sync job (whole job; tenant-scoped).","operationId":"replaySyncJob","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"tenant_id","in":"query"},{"schema":{"type":"string","description":"Application identifier, shown in the Console under My apps."},"required":true,"description":"Application identifier, shown in the Console under My apps.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"Service-key identifier within the application; this is not the secret."},"required":true,"description":"Service-key identifier within the application; this is not the secret.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Request issuance time as canonical unix seconds, within the ±300s window."},"required":true,"description":"Request issuance time as canonical unix seconds, within the ±300s window.","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Single-use request nonce; replay is rejected."},"required":true,"description":"Single-use request nonce; replay is rejected.","name":"x-ir-nonce","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobReplayRequest"}}}},"responses":{"202":{"description":"Replay job enqueued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobReplayResult"}}}},"400":{"description":"Request validation failed — `request.validation_failed`. The body, query, path, header or cookie parameters did not match the declared schema. `errors[]` names each offending field, prefixed with where it was read from (`body.`, `query.`, `path.`, `header.`, `cookie.`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"HMAC invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Tenant mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Job not found in this scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Job not replayable. A Xero refund job always answers refund.replay_requires_continue, before any other check. A prepayment apply whose ERP prepayment was re-bound to another credit after the apply was accepted answers accounting.document_unlinked (reason mapping_changed); nothing is sent (a replay job already created is cancelled unpublished and named by job_id): resend the apply under a new idempotency_key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limited — `rate_limit.shield_shed` (pre-auth IP shield) or `rate_limit.quota_exceeded` (per-app quota). `Retry-After` carries the full window in seconds; re-sign every retry with a fresh `X-IR-Nonce` and `X-IR-Timestamp`.","headers":{"Retry-After":{"description":"Full rate-limit window in seconds — not the time remaining in it.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"webhooks":{"sync_job.completed":{"post":{"tags":["Webhooks"],"operationId":"webhookSyncJobCompleted","summary":"A sync job completed","description":"Sent when a job you started reaches completed. Poll GET /v1/sync-jobs/{id} for the authoritative result.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"sync_job.dead_lettered":{"post":{"tags":["Webhooks"],"operationId":"webhookSyncJobDeadLettered","summary":"A sync job failed for good","description":"Sent when a job stops retrying and is dead-lettered. Read last_error_code, then the job.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"sync_job.resolved":{"post":{"tags":["Webhooks"],"operationId":"webhookSyncJobResolved","summary":"A sync job was resolved by the runtime team","description":"Sent when a job is marked manually_resolved.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"sync_job.failed":{"post":{"tags":["Webhooks"],"operationId":"webhookSyncJobFailed","summary":"Reserved: does not fire today","description":"In the catalog so an endpoint can subscribe to it, but nothing sends it: a failed job is reported once, as sync_job.dead_lettered.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"quickbooks.transaction.status_changed":{"post":{"tags":["Webhooks"],"operationId":"webhookQuickBooksTransactionStatusChanged","summary":"A QuickBooks Invoice or Payment changed","description":"Sent when the runtime's verified view of a QuickBooks Invoice or Payment changes. An endpoint with no event filter receives it.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuickBooksTransactionStatusWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"accounting.document.status_changed":{"post":{"tags":["Webhooks"],"operationId":"webhookAccountingDocumentStatusChanged","summary":"An accounting document the runtime wrote changed (opt-in)","description":"Provider-neutral status of a document the runtime wrote for you (it has your erp_id). Explicit-only: sent only to endpoints that list this event; an endpoint with no event filter never receives it.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountingDocumentStatusWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"connection.connected":{"post":{"tags":["Webhooks"],"operationId":"webhookConnectionConnected","summary":"A connection was connected or reconnected (opt-in)","description":"Sent when a connection becomes connected: the first connect, a reconnect, or a recovery. Explicit-only: sent only to endpoints that list this event. Read GET /v1/connections/{id} for the current state.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionStatusWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"connection.reconnect_required":{"post":{"tags":["Webhooks"],"operationId":"webhookConnectionReconnectRequired","summary":"A connection needs the customer to reconnect (opt-in)","description":"Sent when the provider authorization of a connection stops working. Calls on it fail until the customer reconnects: start a new connect session for the same tenant and provider. Explicit-only: sent only to endpoints that list this event.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionStatusWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"connection.disconnected":{"post":{"tags":["Webhooks"],"operationId":"webhookConnectionDisconnected","summary":"A connection was disconnected (opt-in)","description":"Sent when a connection that had been connected is disconnected. Explicit-only: sent only to endpoints that list this event.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionStatusWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"meeting.artifacts_ready":{"post":{"tags":["Webhooks"],"operationId":"webhookMeetingArtifactsReady","summary":"A meeting's recording or transcript links are ready (opt-in)","description":"Sent at most twice per meeting: once when a recording or transcript first becomes available (stage available), and once when the answer is final (stage final, status available or none). Links only; who can open them follows the organizer's own sharing rules. Explicit-only: sent only to endpoints that list this event. The artifacts read stays the source of truth.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingArtifactsWebhookPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}},"webhook.test":{"post":{"tags":["Webhooks"],"operationId":"webhookTest","summary":"A test event an app owner asked for (not subscribable)","description":"Sent only when an app owner clicks Send test event for one webhook and one customer. It cannot be subscribed to and is never sent otherwise; data names only the webhook. Verify it like any delivery, then answer 2xx.","security":[],"parameters":[{"schema":{"type":"string","description":"Unix seconds when this attempt was signed. Signed (canonical line 4)."},"required":true,"description":"Unix seconds when this attempt was signed. Signed (canonical line 4).","name":"x-ir-timestamp","in":"header"},{"schema":{"type":"string","minLength":22,"maxLength":64,"description":"Fresh for every attempt. Signed (canonical line 5)."},"required":true,"description":"Fresh for every attempt. Signed (canonical line 5).","name":"x-ir-nonce","in":"header"},{"schema":{"type":"string","description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text."},"required":true,"description":"base64url (no padding) HMAC-SHA256 of the canonical payload. The key is the endpoint secret decoded from base64url: its 32 raw bytes, not the 43-character text.","name":"x-ir-signature","in":"header"},{"schema":{"type":"string","description":"Your app id. Not signed."},"required":true,"description":"Your app id. Not signed.","name":"x-ir-app-id","in":"header"},{"schema":{"type":"string","description":"The endpoint's name (key id): selects which secret to verify with. Not signed."},"required":true,"description":"The endpoint's name (key id): selects which secret to verify with. Not signed.","name":"x-ir-key-id","in":"header"},{"schema":{"type":"string","description":"Copy of delivery_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of delivery_id. NOT signed: read the value from the verified body.","name":"x-ir-delivery-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_id. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_id. NOT signed: read the value from the verified body.","name":"x-ir-event-id","in":"header"},{"schema":{"type":"string","description":"Copy of event_type. NOT signed: read the value from the verified body."},"required":true,"description":"Copy of event_type. NOT signed: read the value from the verified body.","name":"x-ir-event-type","in":"header"},{"schema":{"type":"string","description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only."},"required":true,"description":"1-based attempt number, at most 5. NOT signed, and not in the body: use it for logs only.","name":"x-ir-attempt","in":"header"},{"schema":{"type":"string","description":"Present only when the event carries a correlation id. Not signed."},"required":false,"description":"Present only when the event carries a correlation id. Not signed.","name":"x-ir-correlation-id","in":"header"},{"schema":{"type":"string","description":"Always application/json. Not signed."},"required":true,"description":"Always application/json. Not signed.","name":"accept","in":"header"},{"schema":{"type":"string","description":"Always integration-runtime-webhooks/1."},"required":true,"description":"Always integration-runtime-webhooks/1.","name":"user-agent","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestPayload"}}}},"responses":{"408":{"description":"Retried."},"429":{"description":"Retried on the runtime's own schedule; Retry-After is not read."},"2XX":{"description":"Any 2xx means delivered. Answer within 10 seconds and do the work afterwards; a slower answer counts as a timeout and is retried."},"3XX":{"description":"Any 3xx is terminal. Redirects are never followed; fix the registered URL."},"4XX":{"description":"Any 4xx other than 408 and 429 is terminal: the delivery is not retried. Answer 401 when the signature does not verify."},"5XX":{"description":"Any 5xx is retried, up to 5 attempts in total."}}}}}}