> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Apply Settlements > Apply marketplace-agnostic settlement lines to existing orders. ### Authentication Requires `orders:write`. ### What this endpoint does - Stores every submitted line as marketplace financial evidence. - Projects **settled** rows into the order finance ledger. - Keeps pending, reversed, and voided rows as evidence only, removing any earlier developer API ledger projection for the same `sourceEventKey`. - Recomputes Payment received when a marketplace-specific formula exists. Zalora is currently supported. ### Order matching Orders are matched by organization, marketplace platform, and exact `externalOrderId`. Include `externalOrderItemId` when an order has multiple lines. - `accountId` is an exact store match, never a wildcard. - `marketplace=zalora` can match Zalora Seller Center orders (`platform=zalora`) and reconciliation-era agentic carts. - If the same `externalOrderId` exists in both groups, the line is ambiguous. Pass `accountId` to disambiguate it. - Ledger rows retain the platform of the matched order. ### Zalora ITR parity - Send one `lines[]` entry per report row. `transactionType` can represent Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, or credits. - `settlementStatus=settled` is paid; `pending` is not. - Payment received is calculated from Item Price Credit − ZAP − Commission ledger entries. Payment gateway, shipping, and penalty entries still post to P&L when settled but are excluded from that formula. - Item Price Credit updates Payment received without changing line `paidPrice` or `unitPrice`. Use `PATCH /api/v1/orders/{orderId}` when displayed prices must also change. ### Important limitations This is not an order-price API. Selling prices, COGS, and returns belong on `POST /api/v1/orders` or `PATCH /api/v1/orders/{orderId}`. Do not send `paymentReceived`. This endpoint does not replace ITR apply for: - Spreadsheet parsing - Updating `paidPrice` or `unitPrice` - Automatically marking returned or cancelled lines and restoring return inventory - SKU fallback matching - Rewriting order currency or totals - Rebasing COGS currency - Undo or redo Do not apply the same fee lines through both this API and the Zalora Item Transaction Report tool. Their `source_event_key` namespaces differ (`developer_api:…` and `zalora_report:…`), so Payment received would be counted twice. ## 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: agents description: agents x-group: Agents - name: analytics description: Sales performance across marketplaces x-group: Analytics - name: aops description: Agent operating procedures x-group: AOPs - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - 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, enrichment, publish, and delist 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: returns description: returns x-group: Returns - name: reviews description: Marketplace product reviews and seller replies x-group: Reviews - 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. ### Authentication Requires `orders:write`. ### What this endpoint does - Stores every submitted line as marketplace financial evidence. - Projects **settled** rows into the order finance ledger. - Keeps pending, reversed, and voided rows as evidence only, removing any earlier developer API ledger projection for the same `sourceEventKey`. - Recomputes Payment received when a marketplace-specific formula exists. Zalora is currently supported. ### Order matching Orders are matched by organization, marketplace platform, and exact `externalOrderId`. Include `externalOrderItemId` when an order has multiple lines. - `accountId` is an exact store match, never a wildcard. - `marketplace=zalora` can match Zalora Seller Center orders (`platform=zalora`) and reconciliation-era agentic carts. - If the same `externalOrderId` exists in both groups, the line is ambiguous. Pass `accountId` to disambiguate it. - Ledger rows retain the platform of the matched order. ### Zalora ITR parity - Send one `lines[]` entry per report row. `transactionType` can represent Commission, Item Price Credit, ZAP Commitments, Payment Gateway Fee, shipping, penalties, or credits. - `settlementStatus=settled` is paid; `pending` is not. - Payment received is calculated from Item Price Credit − ZAP − Commission ledger entries. Payment gateway, shipping, and penalty entries still post to P&L when settled but are excluded from that formula. - Item Price Credit updates Payment received without changing line `paidPrice` or `unitPrice`. Use `PATCH /api/v1/orders/{orderId}` when displayed prices must also change. ### Important limitations This is not an order-price API. Selling prices, COGS, and returns belong on `POST /api/v1/orders` or `PATCH /api/v1/orders/{orderId}`. Do not send `paymentReceived`. This endpoint does not replace ITR apply for: - Spreadsheet parsing - Updating `paidPrice` or `unitPrice` - Automatically marking returned or cancelled lines and restoring return inventory - SKU fallback matching - Rewriting order currency or totals - Rebasing COGS currency - Undo or redo Do not apply the same fee lines through both this API and the Zalora Item Transaction Report tool. Their `source_event_key` namespaces differ (`developer_api:…` and `zalora_report:…`), so Payment received would be counted twice. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.