Return webhooks

Returns are their own versioned resource. They are not embedded in order.updated because a return can begin after fulfillment and can be approved, rejected, received, refunded, or corrected independently of the order status.

Events

Event	Emitted when
`return.created`	A normalized return and its current lines first commit
`return.updated`	Amounts, identifiers, or SKU-level lines change without a canonical status transition
`return.status.changed`	The provider-neutral return status changes

All three use schemaVersion: "2026-08-29", the standard event ID, resourceVersion, source identity, and complete data.return snapshot.

Statuses

requested | approved | in_transit | received | completed | rejected | cancelled | unknown

marketplaceStatus preserves the provider label. Build business behavior from the normalized status; retain the provider label only for audit and support.

Return snapshot

Field	Meaning
`id`	Stable OmniCommerce return UUID
`orderId`	Matched OmniCommerce order UUID, or `null`
`marketplace`, `accountId`	Provider and exact connected store identity
`externalReturnId`, `externalOrderId`	Marketplace return and order identity
`status`, `marketplaceStatus`	Normalized and original lifecycle status
`refundAmount`	Return-level decimal-string money, or `null`
`itemCount`, `quantity`, `items`	Current SKU-level return outcome
`sourceCreatedAt`, `sourceUpdatedAt`	Marketplace timestamps when supplied
`createdAt`, `updatedAt`	OmniCommerce record timestamps

Each line contains stable internal and provider line IDs, matched productId, marketplace product/variant IDs, SKU aliases, quantity, status, and line refund money. Buyer names, emails, phones, and delivery addresses are excluded.

Example status change

{
  "schemaVersion": "2026-08-29",
  "id": "evt_53c9e0d6fd784aacb84de9863e2f82f7",
  "type": "return.status.changed",
  "occurredAt": "2026-08-29T08:15:00.000Z",
  "publishedAt": "2026-08-29T08:15:01.000Z",
  "organizationId": "org_123",
  "resourceVersion": 3,
  "source": {
    "system": "marketplace",
    "marketplace": "lazada",
    "accountId": "seller-123",
    "providerEventId": null,
    "providerEventType": null
  },
  "subject": {
    "type": "return",
    "id": "11111111-1111-4111-8111-111111111111",
    "externalId": "665434301169671",
    "externalNumber": null
  },
  "data": {
    "return": {
      "id": "11111111-1111-4111-8111-111111111111",
      "orderId": "22222222-2222-4222-8222-222222222222",
      "marketplace": "lazada",
      "accountId": "seller-123",
      "externalReturnId": "665434301169671",
      "externalOrderId": "164962091069671",
      "status": "completed",
      "marketplaceStatus": "REFUND_SUCCESS",
      "country": "SG",
      "currency": "SGD",
      "refundAmount": { "amount": "57.1", "currency": "SGD" },
      "itemCount": 1,
      "quantity": 1,
      "items": [
        {
          "id": "33333333-3333-4333-8333-333333333333",
          "productId": "44444444-4444-4444-8444-444444444444",
          "externalReturnItemId": "665434301269671",
          "marketplaceItemId": "13691971630",
          "marketplaceVariantId": "124573183081",
          "sku": "BX2200MI-MS",
          "sellerSku": "BX2200MI-MS",
          "shopSku": null,
          "name": "Linen wrap dress",
          "status": "REFUND_SUCCESS",
          "quantity": 1,
          "refundAmount": { "amount": "57.1", "currency": "SGD" }
        }
      ],
      "sourceCreatedAt": "2026-08-28T04:00:00.000Z",
      "sourceUpdatedAt": "2026-08-29T08:15:00.000Z",
      "createdAt": "2026-08-28T04:00:02.000Z",
      "updatedAt": "2026-08-29T08:15:00.000Z"
    },
    "previousStatus": "approved",
    "status": "completed",
    "marketplacePreviousStatus": "REFUND_APPROVED",
    "marketplaceStatus": "REFUND_SUCCESS",
    "changedFields": ["status", "marketplaceStatus", "refundAmount", "items"]
  }
}

Pull reconciliation

Use GET /api/v1/returns with returns:read for bootstrap or reconciliation. Filter by marketplace, exact account, external order ID, or updatedSince, and follow the opaque cursor. Use GET /api/v1/returns/{returnId} for one resource. Consumer rules are the same as other versioned webhooks: deduplicate by event id, apply only a newer resourceVersion for one subject.id, replace from the complete snapshot, and ignore unknown additive fields.

Get started

Guides

Webhooks

MCP

Events

Statuses

Return snapshot

Example status change

Pull reconciliation

​Events

​Statuses

​Return snapshot

​Example status change

​Pull reconciliation

Events

Statuses

Return snapshot

Example status change

Pull reconciliation