curl --request POST \
  --url https://omnicommerce.sg/api/v1/settlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "marketplace": "zalora",
  "lines": [
    {
      "externalOrderId": "MY-213127917",
      "externalOrderItemId": "11476389",
      "transactionType": "Commission",
      "amount": -12.5,
      "currency": "MYR",
      "settlementStatus": "settled"
    }
  ]
}
'

{
  "ok": true,
  "apiVersion": "<string>",
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "completed",
  "data": {
    "success": true,
    "marketplace": "<string>",
    "sourceEventKeys": [
      "<string>"
    ],
    "succeededCount": 123,
    "failedCount": 123,
    "evidenceUpserted": 123,
    "ledgerProjected": 123,
    "ledgerUnprojected": 123,
    "paymentReceivedRecomputed": true,
    "paymentReceivedFormulaId": "<string>",
    "orderIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "results": [
      {
        "success": true,
        "sourceEventKey": "<string>",
        "externalOrderId": "<string>",
        "externalOrderItemId": "<string>",
        "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "orderItemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "feeType": "<string>",
        "settlementStatus": "estimated",
        "projected": true,
        "error": "<string>"
      }
    ]
  }
}

Settlements

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.

POST

api

settlements

curl --request POST \
  --url https://omnicommerce.sg/api/v1/settlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "marketplace": "zalora",
  "lines": [
    {
      "externalOrderId": "MY-213127917",
      "externalOrderItemId": "11476389",
      "transactionType": "Commission",
      "amount": -12.5,
      "currency": "MYR",
      "settlementStatus": "settled"
    }
  ]
}
'

{
  "ok": true,
  "apiVersion": "<string>",
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "completed",
  "data": {
    "success": true,
    "marketplace": "<string>",
    "sourceEventKeys": [
      "<string>"
    ],
    "succeededCount": 123,
    "failedCount": 123,
    "evidenceUpserted": 123,
    "ledgerProjected": 123,
    "ledgerUnprojected": 123,
    "paymentReceivedRecomputed": true,
    "paymentReceivedFormulaId": "<string>",
    "orderIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "results": [
      {
        "success": true,
        "sourceEventKey": "<string>",
        "externalOrderId": "<string>",
        "externalOrderItemId": "<string>",
        "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "orderItemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "feeType": "<string>",
        "settlementStatus": "estimated",
        "projected": true,
        "error": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.

Body

application/json

marketplace

string

required

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.

Required string length: 2 - 32

lines

object[]

required

Settlement lines. Plural even for one target. Each line is one fee/credit/reversal, not a net paymentReceived.

Required array length: 1 - 200 elements

Show child attributes

organizationId

string

Optional for OAuth clients bound to one organization; required when the caller can access multiple organizations.

Maximum string length: 120

accountId

string

Exact store/account id. Never a wildcard. Omit only when org + marketplace + externalOrderId already identifies one order.

Maximum string length: 160

Response

Batch accepted. Top-level success is true only when every requested line succeeds; partial failures remain in data.results.

boolean

apiVersion

string

operationId

string<uuid>

status

enum<string>

Available options:

completed,

failed

data

object

Show child attributes

Overview

Endpoints

Webhooks

Apply Settlements

Authentication

What this endpoint does

Order matching

Zalora ITR parity

Important limitations

Authorizations

Body

Response