YOM Docs

Returns

YOM can notify the customer's system of every return request that sellers or commerces record against an order that already exists. When the request is recorded, YOM sends an HTTP POST call to the customer's endpoint with the details of the return, the Order, the Commerce, and the Seller.

The return is for merchandise: it declares which order lines are being returned, in what quantity, and for what reason. YOM neither issues nor manages credit notes.

The customer reports the review result back to YOM through a status webhook, line by line.

<aside> ⚙️

The returns module is enabled per customer from YOM. To activate it, you must give YOM the receiving endpoint URL; unlike other integrations, there is no mandatory standard path here. The general authentication and format requirements are in Technical requirements

</aside>

Endpoint

POST <tu_dominio>/webhooks/yom/refunds

Request body

{
  "refundRequest": { ... },
  "order": { ... },
  "commerce": { ... },
  "seller": { ... }
}

Fields

RefundRequest

The refundRequest entity: the return request itself.

Field Type Requirement Description Examples
requestId 📝 Text 🟢 Required Unique identifier of the Return request. Format RF-YYYYMMDD-<16 characters>.
It is the key the customer uses to report the review result. "RF-20260914-9f3c1a2b8d4e5f60"
domain 📝 Text 🟢 Required Domain of the customer the request belongs to. "cliente.youorder.me"
externalOrderId 📝 Text ⚪ Optional Code of the Order in the customer's system. It identifies the order the return is requested against. "PED-000123456"
orderDate 📅 Date ⚪ Optional Creation date of the original Order, in ISO 8601 format. "2026-09-10T14:22:31.004Z"
externalCommerceId 📝 Text ⚪ Optional Code of the Commerce in the customer's system. "CL-0099231"
externalSellerId 📝 Text ⚪ Optional Code of the Seller in the customer's system. "V-0451"
channel 📝 Text 🟢 Required Channel the request was recorded from.
"app" → seller app
"ecommerce" → commerce platform "app"
status 📝 Text 🟢 Required Overall status of the request. In this call it is always "in_review".
"in_review" · "approved" · "rejected" · "partial"
It is recalculated from the status of each line. "in_review"
items 🔡 List of Objects → RefundItem 🟢 Required Lines being returned. Maximum 200 per request. See details below.
events 🔡 List of Objects ⚪ Optional YOM's internal audit trail: type, name, message, and createdAt.
createdAt 📅 Date 🟢 Required Creation date of the request, in ISO 8601 format. "2026-09-14T11:05:12.881Z"
updatedAt 📅 Date 🟢 Required Date of the last modification of the request, in ISO 8601 format. "2026-09-14T11:05:12.881Z"

RefundItem

Each line of refundRequest.items.

| --- | --- | --- | --- | --- |

ExtraField

Each answer in items[].extraFields. The return form is configurable per customer, so the set of fields depends on each customer's configuration.

| --- | --- | --- | --- | --- |

Order, Commerce, and Seller

The order, commerce, and seller objects are sent complete, with the same structure as in the rest of the integrations.