> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt > Use this file to discover all available pages before exploring further. # Apply Settlements > Apply marketplace-agnostic settlement lines to existing orders. Writes marketplace financial evidence, projects **settled** rows into the order finance ledger, and recomputes Payment received when a marketplace formula exists (Zalora today). Pending, reversed, and voided rows stay on evidence only and un-project any earlier developer-API ledger row for that sourceEventKey. This is not an order-price API: selling prices, COGS, and returns stay on `POST/PATCH /api/v1/orders`. Do not send `paymentReceived`. Requires `orders:write`. Match is organization + marketplace order platform + exact `externalOrderId` (and `externalOrderItemId` when the order has multiple lines). `accountId` is an exact store match, never a wildcard. `marketplace=zalora` matches orders imported from Zalora Seller Center (`platform=zalora`) as well as reconciliation-era agentic carts; ledger rows keep whichever platform the matched order has. If one `externalOrderId` exists under both, the line fails as ambiguous — pass `accountId` to disambiguate. **Zalora ITR parity:** send one `lines[]` entry per report row (`transactionType` such as Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, credits — Omni maps fee types like the ITR parser). `settlementStatus=settled` is paid; `pending` is not. Payment received (Zalora) recomputes from Item Price Credit − ZAP − Commission ledger legs only; PG, shipping, and penalties still post to P&L when settled but are excluded from that formula, same as ITR. Item Price Credit here updates Payment received via the ledger without changing line `paidPrice`/`unitPrice` — PATCH `/api/v1/orders/{orderId}` when displayed prices must match. **Does not replace ITR apply for:** parsing spreadsheets, writing `paidPrice`/`unitPrice`, auto-marking returned/cancelled lines (and return inventory restock), SKU fallback matching, order currency/total rewrite, COGS currency rebase, or undo/redo. Do not apply the same fee lines through this API and the Zalora Item Transaction Report tool — `source_event_key` namespaces differ (`developer_api:…` vs `zalora_report:…`) and Payment received will double-count. ## OpenAPI ````yaml /openapi.json post /api/v1/settlements openapi: 3.1.0 info: title: OmniCommerce API version: 1.0.0 license: name: Proprietary url: https://omnicommerce.sg/terms description: >- OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens). servers: - url: https://omnicommerce.sg description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: agentic-checkout description: Merchant-fulfilled agentic checkout x-group: Agentic Checkout - name: commerce description: Root commerce discovery x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: looks description: AI-styled product looks x-group: Looks - name: oauth description: OAuth token endpoints x-group: OAuth - name: orders description: Workspace and agentic orders x-group: Orders - name: organizations description: Organization management x-group: Organizations - name: price-books description: Marketplace list-price markup rules x-group: Price Books - name: products description: Product CRUD, bulk import, and publish x-group: Products - name: promotions description: Central promotions and marketplace sync x-group: Promotions - name: public-agent description: Public agent discovery and catalog APIs x-group: Public Agent - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/settlements: post: tags: - settlements summary: Apply Settlements description: >- Apply marketplace-agnostic settlement lines to existing orders. Writes marketplace financial evidence, projects **settled** rows into the order finance ledger, and recomputes Payment received when a marketplace formula exists (Zalora today). Pending, reversed, and voided rows stay on evidence only and un-project any earlier developer-API ledger row for that sourceEventKey. This is not an order-price API: selling prices, COGS, and returns stay on `POST/PATCH /api/v1/orders`. Do not send `paymentReceived`. Requires `orders:write`. Match is organization + marketplace order platform + exact `externalOrderId` (and `externalOrderItemId` when the order has multiple lines). `accountId` is an exact store match, never a wildcard. `marketplace=zalora` matches orders imported from Zalora Seller Center (`platform=zalora`) as well as reconciliation-era agentic carts; ledger rows keep whichever platform the matched order has. If one `externalOrderId` exists under both, the line fails as ambiguous — pass `accountId` to disambiguate. **Zalora ITR parity:** send one `lines[]` entry per report row (`transactionType` such as Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, credits — Omni maps fee types like the ITR parser). `settlementStatus=settled` is paid; `pending` is not. Payment received (Zalora) recomputes from Item Price Credit − ZAP − Commission ledger legs only; PG, shipping, and penalties still post to P&L when settled but are excluded from that formula, same as ITR. Item Price Credit here updates Payment received via the ledger without changing line `paidPrice`/`unitPrice` — PATCH `/api/v1/orders/{orderId}` when displayed prices must match. **Does not replace ITR apply for:** parsing spreadsheets, writing `paidPrice`/`unitPrice`, auto-marking returned/cancelled lines (and return inventory restock), SKU fallback matching, order currency/total rewrite, COGS currency rebase, or undo/redo. Do not apply the same fee lines through this API and the Zalora Item Transaction Report tool — `source_event_key` namespaces differ (`developer_api:…` vs `zalora_report:…`) and Payment received will double-count. operationId: post_v1_settlements requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - marketplace - lines properties: organizationId: type: string maxLength: 120 description: >- Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations. marketplace: type: string minLength: 2 maxLength: 32 description: >- Settlement source marketplace slug (zalora, shopee, lazada, tiktok, shopify, agentic, …). Used to match orders and pick a payment-received formula. `zalora` matches both Seller Center orders (`platform=zalora`) and reconciliation-era agentic carts. accountId: type: string maxLength: 160 description: >- Exact store/account id. Never a wildcard. Omit only when org + marketplace + externalOrderId already identifies one order. lines: type: array minItems: 1 maxItems: 200 description: >- Settlement lines. Plural even for one target. Each line is one fee/credit/reversal, not a net paymentReceived. items: type: object additionalProperties: false required: - externalOrderId - amount - currency - settlementStatus properties: externalOrderId: type: string maxLength: 160 description: Exact order identifier stored on the Omni order. externalOrderItemId: type: string maxLength: 160 description: >- Required when the order has more than one line. Exact marketplace/item id. sourceEventKey: type: string maxLength: 240 description: >- Optional idempotency key. Omni namespaces it under developer_api:{marketplace}:… externalTransactionId: type: string maxLength: 240 description: >- Marketplace transaction number used to derive sourceEventKey when omitted. transactionType: type: string maxLength: 160 description: >- Source label (e.g. Commission). Used to derive feeType when feeType is omitted. feeType: type: string maxLength: 160 description: >- Stored ledger fee_type. Prefer this when you already have a sanitized key. amount: type: number description: >- Non-zero signed amount in line currency. Positive is seller credit unless direction is set. currency: type: string minLength: 3 maxLength: 3 description: ISO-4217. Must match the order/line currency. direction: type: string enum: - credit - debit description: >- Optional. When omitted, a negative amount is debit and a positive amount is credit. settlementStatus: type: string enum: - estimated - pending - settled - reversed - voided description: >- Only settled rows project into the finance ledger. Other statuses remain evidence. occurredAt: type: string format: date-time settlementReference: type: string maxLength: 240 payoutReference: type: string maxLength: 240 examples: zaloraCommission: summary: Zalora settled commission on an agentic order line value: organizationId: org_123 marketplace: zalora lines: - externalOrderId: MY-213127917 externalOrderItemId: '11476389' transactionType: Commission amount: -12.5 currency: MYR settlementStatus: settled shopeePending: summary: Shopee pending fee (evidence only) value: marketplace: shopee accountId: shop-1 lines: - externalOrderId: SO-1001 externalOrderItemId: ITEM-1 feeType: commission amount: -3.2 currency: SGD settlementStatus: pending externalTransactionId: ESC-99 responses: '200': description: >- Batch accepted. Top-level success is true only when every requested line succeeds; partial failures remain in data.results. content: application/json: schema: type: object properties: ok: type: boolean apiVersion: type: string operationId: type: string format: uuid status: type: string enum: - completed - failed data: type: object properties: success: type: boolean description: True only when every requested line succeeds. marketplace: type: string sourceEventKeys: type: array items: type: string succeededCount: type: integer failedCount: type: integer evidenceUpserted: type: integer ledgerProjected: type: integer ledgerUnprojected: type: integer paymentReceivedRecomputed: type: boolean paymentReceivedFormulaId: type: - string - 'null' description: >- Set when a marketplace formula exists (zalora_payment_received_v1 today). orderIds: type: array items: type: string format: uuid results: type: array items: type: object properties: success: type: boolean sourceEventKey: type: string externalOrderId: type: string externalOrderItemId: type: - string - 'null' orderId: type: string format: uuid orderItemId: type: string format: uuid feeType: type: - string - 'null' settlementStatus: type: string enum: - estimated - pending - settled - reversed - voided projected: type: boolean error: type: string '400': description: Bad Request — invalid payload '401': description: Unauthorized '403': description: Forbidden or missing `orders:write` scope '429': description: Rate limit exceeded '500': description: Internal Server Error security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows. ````