> ## 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.

# Settlements API

> Apply marketplace fees, credits, settlement status, and order-level finance evidence.

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

```http theme={null}
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

```http theme={null}
POST /api/v1/settlements
```

```json theme={null}
{
  "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

1. Upserts `marketplace_financial_evidence` (`source_kind=developer_api`).
2. Projects **settled** rows to `order_financial_events` using the **order's** platform and `account_id` (exact join, including `NULL`).
3. Un-projects a previous developer-API ledger row when the same `sourceEventKey` is later sent as pending / reversed / voided.
4. 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.

```json theme={null}
{
  "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.