YOM Docs

Untitled

Delivery price

YOM can delegate the calculation of an order's delivery cost to the customer's system. When a commerce or a seller quotes or confirms an order, YOM sends an HTTP POST request to the customer's endpoint with the Order details. The customer responds with the net delivery cost, or indicates that it cannot quote it.

<aside> 📝

The customer only needs to expose the endpoint and give YOM its URL. No other configuration is required.

</aside>

When YOM calls it

The query happens at four moments, always synchronously:

• Advance quote from the seller's order taker.
• Advance quote from the B2B web platform.
• On order creation from the B2B web platform.
• On order creation from the seller's order taker.

A single order therefore produces more than one call: at least one when quoting on screen and another when confirming it.

<aside> ⚠️

The query is skipped entirely when the commerce has no code in the customer's system. Without order.externalId there is no quote and the order is created with delivery at 0.

</aside>

Endpoint

POST <tu_dominio>/webhooks/yom/order/delivery-price

Request body

{
  "order": { ... }
}

Fields

Order

The order entity, inside the body's order key.

ShippingAddress

The order.shippingAddress object, with the delivery destination.

<aside> ℹ️

In advance quotes the order does not exist yet: it is a draft built from what is on screen. Only the fields marked as required are guaranteed; the rest may arrive empty or absent.

</aside>

Expected response

The endpoint must respond 200 with Content-Type: application/json.

<aside> 🚨

The netValue field must always be present. YOM validates transportationCost but stores netValue: a response that carries the first and omits the second is accepted as a valid quote and leaves the order with delivery at 0, with no visible error. This is the most common failure when connecting a new integration.

</aside>

Quoted delivery

{
  "transportationCost": 1500,
  "netValue": 1500,
  "netTaxedValue": 1785,
  "taxesApplied": {"code": 14, "value": 0.19}
}

Free delivery

{
  "transportationCost": 0,
  "netValue": 0,
  "netTaxedValue": 0,
  "taxesApplied": {"code": 14, "value": 0.19}
}

No quote

A 200 response that does not include transportationCost is interpreted as no quote having been returned. The order is still created, with delivery at 0, unless the customer has the quote requirement turned on.

{}

Rejection with a reason

When the delivery cannot be quoted for a business reason — commune outside the coverage area, maximum weight exceeded, delivery window unavailable —, the endpoint must respond with a 4xx status and the explanation in the body. YOM takes it and shows it to the user as is.

The text is looked up, in this order, in errors.message, detail, or message; if the body is plain text, the whole body is used.

HTTP/1.1 422
Content-Type: application/json

{
  "message": "No existen parámetros de despacho hacia la comuna de destino."
}

The user sees that same text on screen and the order does not move forward.

<aside> 🛑

A 5xx is never interpreted as a rejection. A server error is an infrastructure failure, not a business decision: it turns into a generic error the buyer cannot resolve. To communicate a reason, you must respond 4xx.

</aside>

Example

POST <https://api.cliente.com/webhooks/yom/order/delivery-price>
Content-Type: application/json
Accept: application/json
x-auth-token: 6a5a8ee27726337b51c72405
origin: legacy.youorder.me

{
  "order": {
    "externalId": "10023456",
    "domain": "cliente.youorder.me",
    "commerceId": "6412f0a1b2c3d4e5f6a7b8c9",
    "commerceName": "Minimarket Los Aromos",
    "distributionCenterId": "64aa11bb22cc33dd44ee55ff",
    "estimatedDeliverAt": "2026-09-18T00:00:00.000Z",
    "type": "order",
    "status": "pending",
    "shippingAddress": {
      "name": "Bodega central",
      "address": "Av. Siempre Viva 742",
      "commune": "Maipú",
      "city": "Santiago",
      "metadata": {
        "coordinates": {"latitude": -33.5110, "longitude": -70.7580},
        "administrativeAreaLevel1": {"longName": "Región Metropolitana"},
        "country": {"longName": "Chile"}
      }
    },
    "products": [
      {"sku": "SKU-001", "quantity": 12, "pricing": {"totalPrice": 35880}}
    ],
    "pricing": {
      "totalPrice": 35880,
      "netTotalPrice": 30151,
      "finalTotalPrice": 35880,
      "shipping": {"netValue": 0, "netTaxedValue": 0}
    }
  }
}

curl -X POST \
  '<https://api.cliente.com/webhooks/yom/order/delivery-price>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-auth-token: 6a5a8ee27726337b51c72405' \
  -d '{"order": { ... }}'

Considerations

<aside> ⏱️

The endpoint must respond in less than 30 seconds. After 60 seconds the connection is dropped and the quote is lost.

</aside>

• There are no retries. Each quote is a single call.
• The endpoint must be read-only and idempotent. A single order produces several calls.
• Amounts are in the customer's currency. The contract includes no currency field: the same currency as the rest of the order is assumed. You should return all three amounts already rounded to that currency's precision.
• The delivery cost is not added to the order total. It is sent as a separate amount, and it reaches the customer's system that way as well.
• A failed quote does not prevent the order from being created. By default the order is created with delivery at 0. If the customer prefers that an order without a quote cannot be created, YOM can turn that requirement on; in that case the buyer sees the reason for the rejection.
• The order object includes additional fields beyond those described in this document. We recommend using only the fields you need and tolerating the appearance of new fields.