Settlements API

Use POST /api/v1/settlements to apply marketplace settlement lines to existing orders. This is not the Orders API. POST / PATCH /api/v1/orders still own selling prices, COGS, and returns. Settlements write financial evidence, project settled rows into the finance ledger, and recompute Payment received when a marketplace formula exists. Do not send paymentReceived. Omni computes it from settled ledger fee types.

Authentication

Authorization: Bearer omni_sk_...
Content-Type: application/json

Endpoint	Required scope
`POST /api/v1/settlements`	`orders:write`

Session-authenticated calls must include organizationId in the JSON body.

Apply settlements

POST /api/v1/settlements

{
  "marketplace": "zalora",
  "lines": [
    {
      "externalOrderId": "MY-213127917",
      "externalOrderItemId": "11476389",
      "transactionType": "Item Price Credit",
      "amount": 2630,
      "currency": "MYR",
      "settlementStatus": "settled"
    },
    {
      "externalOrderId": "MY-213127917",
      "externalOrderItemId": "11476389",
      "transactionType": "Commission",
      "amount": -80,
      "currency": "MYR",
      "settlementStatus": "settled"
    }
  ]
}

lines is always an array, even for one target. Maximum 200 lines.

Request fields

Field	Required	Notes
`marketplace`	Yes	Settlement source slug: `zalora`, `shopee`, `lazada`, `tiktok`, `shopify`, `agentic`, or another stored platform. Zalora finance matches agentic orders.
`accountId`	No	Exact store id. Never a wildcard. Required only when the same external order id exists on more than one store.
`lines[].externalOrderId`	Yes	Exact Omni order `externalOrderId`.
`lines[].externalOrderItemId`	When the order has more than one line	Exact line id.
`lines[].feeType` or `lines[].transactionType`	One of the two	`feeType` is stored as-is (sanitized). If omitted, Omni derives it from `transactionType`. Zalora aliases still apply (`Commission Credit` → `reversal_commission`).
`lines[].amount`	Yes	Non-zero. Signed: positive = seller credit unless `direction` is set.
`lines[].currency`	Yes	Must match the order/line currency.
`lines[].settlementStatus`	Yes	`estimated` \| `pending` \| `settled` \| `reversed` \| `voided`. Only settled rows enter the finance ledger.
`lines[].sourceEventKey`	No	Idempotency key. Omni namespaces it as `developer_api:{marketplace}:…`.
`lines[].externalTransactionId`	No	Used to derive `sourceEventKey` when omitted.

What Omni writes

Upserts marketplace_financial_evidence (source_kind=developer_api).
Projects settled rows to order_financial_events using the order’s platform and account_id (exact join, including NULL).
Un-projects a previous developer-API ledger row when the same sourceEventKey is later sent as pending / reversed / voided.
Recomputes Payment received only when a formula exists for that marketplace (Zalora today: Item Price − ZAP − Commission).

Selling prices (paidPrice / unitPrice) are not rewritten. Use the Orders API for those.

Matching

Organization-scoped, exact:

marketplace → order platform (zalora → agentic; other slugs match orders.platform)
externalOrderId
externalOrderItemId when more than one line exists
accountId if provided

A missing accountId never matches every store that reuses an external id.

Response

Top-level success is true only when every requested line succeeds. Partial failures stay in data.results in request order.

{
  "ok": true,
  "apiVersion": "developer_v1",
  "status": "completed",
  "data": {
    "success": true,
    "marketplace": "zalora",
    "succeededCount": 2,
    "failedCount": 0,
    "evidenceUpserted": 2,
    "ledgerProjected": 2,
    "paymentReceivedRecomputed": true,
    "paymentReceivedFormulaId": "zalora_payment_received_v1",
    "orderIds": ["11111111-1111-4111-8111-111111111111"],
    "results": []
  }
}

Zalora vs the assistant tool

This API replaces update_zalora_orders_from_transaction_file for structured settlement writes. Do not apply both for the same fee lines — that would double-count Payment received. Continue to use the Orders API for identity, USD COGS, and returns. Continue to use the Item Transaction Report tool only when you want Omni to parse the spreadsheet.

Get started

Guides

MCP

Authentication

Apply settlements

Request fields

What Omni writes

Matching

Response

Zalora vs the assistant tool

​Authentication

​Apply settlements

​Request fields

​What Omni writes

​Matching

​Response

​Zalora vs the assistant tool

Authentication

Apply settlements

Request fields

What Omni writes

Matching

Response

Zalora vs the assistant tool