> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # Match a payout to a deposit > Pairs an inbound bank transaction with an unmatched, posted marketplace payout (Shopify, Amazon, or eBay), atomically linking the two records and flipping the transaction to matched. When the payout's own journal entry was booked against a different bank account, the match also posts a settlement-correction entry to move the deposit onto the right bank unless `skip_settlement_correction` is set; requires `accounting:write` scope and is idempotent via the `Idempotency-Key` header. ## OpenAPI ````yaml /openapi.yaml post /entities/{entity_id}/reconciliation/match-marketplace-payout openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. **Changelog.** Entries are dated and name every published contract whose MEANING moved, not only the ones whose field names changed. The narrative version of the same entries, written for integrators, is published at https://arcuserp.mintlify.app/changelog. **2026-09-22 (planned 2026-09-21), REORDER-BUYER-TRUTH: demand changed what it MEANS on three published contracts, with no field renamed.** An integrator that pins field names sees no breakage and different numbers, which is why this entry exists. - **Demand now counts build consumption.** `demand_avg_per_day` on the public product, kit and inventory-balance objects, and `daily_demand` / `demand_basis` / `net_suggested_qty` on `GET /v1/purchasing/reorder-report`, are composed from fulfilled sales lines PLUS posted `build_consume` inventory draws: each physical decrement of a product counts exactly once. The previous rule adopted an internal-consumption basis only when the sales blend was exactly zero, so a product both sold AND consumed into work orders planned as if the build draws did not exist. Products drawn into work orders move; on one production-shaped dataset five did, the largest from 0.05/day to 14.95/day. - **`demand_basis` now carries four values, not two:** `sales`, `sales_and_builds`, `builds` and `consumption`. A consumer with a two-branch reader (anything that is not `consumption` is `sales`) silently hides the two new ones. - **`current_demand_units` on `GET /v1/inventory/balances/:id` moved, by a second rule.** It counts committed-but-unshipped CUSTOMER demand, and it now counts a kit component's own line rather than its parent kit line, and excludes non-sales documents. On one production dataset 269 of 1,043 balance rows changed, 227 of them downward; the largest single move was 1,941 to 25, on a product whose open PURCHASE order line had been reported as customer demand. Re-baseline anything that alerts or reorders off this field. - `run_rate_30/90/180/365` and `blended_daily` on the same balance object move for the first reason above. - **Added, not changed:** `GET /v1/purchasing/reorder-report` accepts `demand_window` and returns the unit, cover-through and reorder-point-provenance fields documented on that operation; `order_multiple` is accepted and returned on the product-vendor doors. - **Volume note.** The `inventory.low_stock`, `inventory.out_of_stock` and `inventory.back_in_stock` webhook events are population-gated on `on_hand <= reorder_point`, and reorder points move with the demand above, so subscribers should expect a one-time step change in event volume around the release. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /entities/{entity_id}/reconciliation/match-marketplace-payout: post: tags: - Reconciliation summary: Match a payout to a deposit description: >- Pairs an inbound bank transaction with an unmatched, posted marketplace payout (Shopify, Amazon, or eBay), atomically linking the two records and flipping the transaction to matched. When the payout's own journal entry was booked against a different bank account, the match also posts a settlement-correction entry to move the deposit onto the right bank unless `skip_settlement_correction` is set; requires `accounting:write` scope and is idempotent via the `Idempotency-Key` header. operationId: postReconciliationMatchMarketplacePayout parameters: - name: entity_id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: Deduplicates retried match submissions for 24 hours. requestBody: required: true content: application/json: schema: type: object required: - bank_transaction_id - marketplace_payout_id properties: bank_transaction_id: type: string format: uuid description: The inbound bank transaction to match. marketplace_payout_id: type: string format: uuid description: The unmatched, posted marketplace payout to pair with it. reconciliation_id: type: string format: uuid nullable: true description: Optional open bank-reconciliation to attach the match to. skip_settlement_correction: type: boolean default: false description: >- Record the match without correcting the journal entry when the payout settles a different bank account than the transaction. The match still succeeds and the bank side still ties; the general-ledger side stays on the account it is on. The choice is recorded on the audit trail for the match. responses: '200': description: >- Match recorded. A settlement correction is posted only when the payout settles a different bank account than the matched transaction and `skip_settlement_correction` was not sent; `settlement_correction.status` says which happened. content: application/json: schema: type: object properties: bank_transaction_id: type: string format: uuid marketplace_payout_id: type: string format: uuid platform: type: string matched: type: boolean amount_warning: type: string nullable: true description: >- Set when bank and payout amounts differ by more than $0.05. bank_account_warning: type: string nullable: true description: >- A plain sentence for the operator when the payout settles a different bank account, saying what was done about it. Null when the banks agree or the payout's bank cannot be attributed. bank_account_scope: type: string enum: - same_bank_account - different_bank_account - unknown_bank_account description: >- Whether the payout's journal entry settles the same bank as the matched transaction. `unknown_bank_account` means the entry has no single bank leg to compare, which is not a mismatch. settlement_correction: $ref: '#/components/schemas/SettlementCorrection' settlement_mapping: type: object nullable: true description: >- Set when this match taught Arcus which bank account a processor destination pays into, so later payouts from the same destination book to the right bank without anyone configuring it. Learned only from an explicit match by a named user. properties: status: type: string enum: - learned - updated - not_confirmed - not_written platform: type: string external_destination_id: type: string nullable: true bank_account_id: type: string format: uuid nullable: true book_side: $ref: '#/components/schemas/BookSideStamp' correction_book_side: type: array description: >- The settlement-correction entries whose bank line was marked cleared by this match, so the cleared balance follows the correction rather than staying on the original entry. items: type: object properties: role: type: string enum: - reclass - unbook - arrival entry_number: type: string stamped: type: integer reason: type: string nullable: true '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: schemas: SettlementCorrection: type: object description: > What happened to the GENERAL LEDGER when you matched a connector deposit to a bank line. Added 2026-09-19 by BANKFEED wave 4 lane W4-F2. A processor states which bank account it paid, on every payout. Arcus used to book every payout to one bank account configured per platform, so when the settlement bank changed, deposits kept landing on the old account in the books while the cash landed in the new one at the bank. Matching the deposit to the real bank line is the moment Arcus learns the truth, and this object says what it did with it. `status` is the field to switch on: * `posted` a correction was written. `shape` says which. * `not_applicable` the banks already agree, or the payout has no single bank leg to compare. * `not_needed` right bank, right day: there is nothing to correct. * `pending_operator_review` the payout settles a different bank, but this match was automatic or part of a bulk approve, and Arcus never moves money in the ledger without a person asking. Open the payout and match it yourself to correct the books. * `skipped_by_operator` you asked for the match without the correction. * `not_resolvable` the payout, one of the two banks, or the date to post on could not be resolved. `reason` says which: `payout_has_no_journal_entry`, `settle_bank_gl_unresolved`, `target_bank_gl_unresolved`, or `bank_line_has_no_date` when the bank line being matched carries no date to post the correction on. Nothing is posted and the match itself still succeeds. * `entry_not_live` the payout's journal entry is voided or reversed. `shape` says how the correction was written: * `reclass_only` one entry, dated on the payout date, moving the deposit from the bank it was booked to onto the bank it was paid into. * `redate_and_reclass` the payout entry was ALSO dated in a later month than the day the money arrived, so the correction is a dated pair: one entry removes the deposit from the month it was wrongly booked in, the other records it in the month it arrived. Each month closes on the truth, and the clearing account carries the money in between, which is where it genuinely was. * `redate_only` the bank was right and only the month was wrong. The ledger effect of any shape is zero: every entry balances, and the trial balance is the same to the cent before and after. What moves is which bank account, and which month, holds the deposit. properties: status: type: string enum: - posted - not_applicable - not_needed - pending_operator_review - skipped_by_operator - not_resolvable - entry_not_live - blocked_period - not_explicit - no_clearing_leg - payout_date_after_entry_date - invalid_argument posted: type: boolean shape: type: string nullable: true enum: - none - reclass_only - redate_only - redate_and_reclass reason: type: string nullable: true description: Why nothing was posted, when nothing was. corrects_entry_number: type: string nullable: true description: The payout journal entry this correction is about. payout_date: type: string format: date nullable: true description: >- The day the money reached the bank. Every correction is dated here. On a match it is the matched bank line's own transaction date, which is measured rather than reported and therefore outranks the date the processor says it initiated the transfer. entry_date: type: string format: date nullable: true description: The day the payout's own journal entry carries. amount: type: number nullable: true entries: type: array items: type: string description: The entry numbers written, in date order. Empty when nothing posted. legs: type: array description: One per entry written. items: type: object properties: role: type: string enum: - reclass - unbook - arrival entry_date: type: string format: date entry_number: type: string amount: type: number source_type: type: string enum: - RECLASSIFICATION - CORRECTION idempotent: type: boolean nullable: true description: >- True when this exact correction already existed, so nothing new was written. Matching the same payout twice is safe. baseline_adoptions: type: array description: >- Correction lines that were marked cleared on the spot because they are dated on or before a bank account's reconciliation baseline. A line inside a signed-off window has to be adopted into it, or the next session would open on a balance that no longer matches. items: type: object properties: role: type: string entry_number: type: string bank_account_id: type: string format: uuid anchor: type: string format: date stamped: type: integer BookSideStamp: type: object nullable: true description: | What the GENERAL LEDGER now says about the money this bank line explains. Added 2026-09-19 by BANKFEED wave 4 lane W4-G, and it is purely additive: no request field changed and no existing response field changed meaning. A bank reconciliation has two sides. The bank side is `reconciliation_status` on the bank transaction. The BOOK side is `reconciled_at` on the journal entry's line on that bank account's GL account, and until this lane no verb outside a statement session ever wrote it, so matched money could read UNCLEARED in the ledger forever. STILL NO GL IS POSTED. The stamp writes no debit and no credit; the trial balance is identical before and after, and a closed period cannot be moved by it. What it changes is which lines the reconciliation workbench and the bank register's open-items tile still treat as outstanding. `stamped: 0` with a `reason` is an honest answer, not an error: `no_leg_on_bank_gl` means the entry carries no line on THIS account's GL (a payout settled to a different account, for example); `already_reconciled` means a session or a baseline had already cleared it; `missing_argument` means the record carries no journal entry to stamp. properties: stamped: type: integer description: How many journal-entry lines were stamped. Normally 0 or 1. line_ids: type: array items: type: string format: uuid description: The journal_entry_lines rows that were stamped. reason: type: string nullable: true enum: - no_leg_on_bank_gl - already_reconciled - entry_not_live - missing_argument - stamp_failed description: Null when a line was stamped; otherwise why none was. historical_import: type: boolean description: | True when the stamped entry came from a data migration. Recorded so the class is countable; a migrated document whose cash really did clear the bank is cleared, and saying otherwise would leave it outstanding forever. correction_legs: type: array description: > WHICH ENTRIES ANSWERED, when the book side was not on the entry you matched. Added 2026-09-23 by BANKFEED wave 4 lane R6-AN. A settlement correction repairs by POSTING and never by mutating, so after one the ORIGINAL entry keeps only its line on the bank the money was never in, and the line this bank account actually clears belongs to the CORRECTION. Before this, a match on such a payout reported `no_leg_on_bank_gl` (a true sentence about the wrong entry), left the real book side uncleared, and the same cash went on being offered as an unlinked-cash candidate for a second bank line. Empty on every ordinary match, including one whose own correction this same request posted. Non-empty only when a live PRE-EXISTING correction held the book side; `stamped` is then the count from those entries and `reason` is null, exactly as if the line had been found on the entry itself. items: type: object properties: journal_entry_id: type: string format: uuid entry_number: type: string entry_date: type: string format: date stamped: type: integer description: Lines stamped on this correction entry. Normally 0 or 1. ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent__ Test keys use ark_test_ent__. Both are issued per entity via Settings > Developers > API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.