Settlement webhooks

Settlement webhooks are separate from order.updated. Marketplace finance can arrive hours or days after an order, and providers can later adjust, reverse, or void the same financial evidence. OmniCommerce treats a Shopee, Lazada, TikTok Shop, Shopify, Zalora, or Amazon push as a signal. It fetches the marketplace’s authoritative finance detail, normalizes it into one order-and-currency settlement aggregate, and emits a developer webhook only when that committed aggregate changes.

Events

Event	Emitted when
`settlement.created`	The first finance aggregate for one order and currency is committed
`settlement.updated`	Amounts, fees, references, evidence counts, or reconciliation results change
`settlement.status.changed`	Aggregate status changes, including pending, settled, reversed, or voided

Subscribe with POST /api/v1/webhooks. These keys can be combined with product, order, return, and look events in the same subscription. Use GET /api/v1/settlements with settlements:read for bootstrap and pull reconciliation, and GET /api/v1/settlements/{settlementId} for one latest snapshot. The pull API represents snapshots created by this event pipeline; run the finance backfill before expecting older historical orders.

Example

The Lazada finance panel shown in OmniCommerce is represented as normalized money fields and an auditable fee breakdown:

{
  "schemaVersion": "2026-08-29",
  "id": "evt_01J...",
  "type": "settlement.status.changed",
  "occurredAt": "2026-08-29T04:15:00.000Z",
  "publishedAt": "2026-08-29T04:15:02.000Z",
  "organizationId": "org_123",
  "resourceVersion": 3,
  "source": {
    "system": "marketplace",
    "marketplace": "lazada",
    "accountId": "seller_456",
    "providerEventId": null,
    "providerEventType": "finance.synced"
  },
  "subject": {
    "type": "order_settlement",
    "id": "stl_92d31ec6d08a42f99a9af81e6f9a7ba4",
    "externalId": "1234567890",
    "externalNumber": "1234567890"
  },
  "data": {
    "previousStatus": "pending",
    "status": "settled",
    "changedFields": [
      "status",
      "marketplaceNet",
      "feeBreakdown",
      "evidenceCounts"
    ],
    "settlement": {
      "id": "stl_92d31ec6d08a42f99a9af81e6f9a7ba4",
      "orderId": "ord_123",
      "marketplace": "lazada",
      "accountId": "seller_456",
      "externalOrderId": "1234567890",
      "externalOrderNumber": "1234567890",
      "currency": "SGD",
      "status": "settled",
      "grossSales": { "amount": "17.88", "currency": "SGD" },
      "refunds": { "amount": "0", "currency": "SGD" },
      "subsidies": { "amount": "1.99", "currency": "SGD" },
      "platformFees": { "amount": "2.54", "currency": "SGD" },
      "fulfillmentFees": { "amount": "4.29", "currency": "SGD" },
      "operatingFees": { "amount": "0", "currency": "SGD" },
      "marketplaceNet": { "amount": "13.04", "currency": "SGD" },
      "calculatedNet": { "amount": "13.04", "currency": "SGD" },
      "variance": { "amount": "0", "currency": "SGD" },
      "paymentReceived": null,
      "reconciliationStatus": "reconciled",
      "reconciliationExceptionReason": null,
      "settlementReference": "LZD-PAYOUT-20260829",
      "payoutReference": null,
      "feeBreakdown": [
        {
          "feeType": "item_price_credit",
          "category": "gross_sales",
          "amount": { "amount": "17.88", "currency": "SGD" }
        },
        {
          "feeType": "shipping_fee_voucher_by_lazada",
          "category": "subsidies",
          "amount": { "amount": "1.99", "currency": "SGD" }
        },
        {
          "feeType": "commission",
          "category": "platform_fees",
          "amount": { "amount": "1.95", "currency": "SGD" }
        },
        {
          "feeType": "payment_fee",
          "category": "platform_fees",
          "amount": { "amount": "0.59", "currency": "SGD" }
        },
        {
          "feeType": "shipping_fee_paid_by_seller",
          "category": "fulfillment",
          "amount": { "amount": "4.29", "currency": "SGD" }
        }
      ],
      "evidenceCounts": {
        "estimated": 0,
        "pending": 0,
        "settled": 5,
        "reversed": 0,
        "voided": 0
      },
      "sourceOccurredAt": "2026-08-29T04:15:00.000Z",
      "updatedAt": "2026-08-29T04:15:00.000Z"
    }
  }
}

All money values are decimal strings paired with an ISO 4217 currency. Never sum settlement resources across currencies without an explicit FX conversion.

Status model

Status	Meaning
`estimated`	Only estimated finance evidence is available
`pending`	Marketplace finance exists but is not final
`partially_settled`	Some evidence settled while other effective evidence is pending
`settled`	All effective evidence is settled
`reversed`	No effective evidence remains and a prior observation reversed
`voided`	No effective evidence remains and observations were voided

paymentReceived, when present, is a separate formula-backed unit-economics value with formulaId and formulaVersion. It is not the seller settlement net and should not replace marketplaceNet.

Processing guidance

Use id as the delivery idempotency key. Track the highest resourceVersion for each subject.id, and ignore older versions that arrive out of order. Apply the complete data.settlement snapshot rather than incrementally replaying changedFields. If a provider push arrives before finance is ready, OmniCommerce does not expose the provider’s partial body. A later finance refresh creates or updates the normalized settlement resource. Duplicate source upserts that do not change the resource produce no new public event.

Get started

Guides

Webhooks

MCP

Events

Example

Status model

Processing guidance

​Events

​Example

​Status model

​Processing guidance

Events

Example

Status model

Processing guidance