Purpose
This allows ordering platforms to pre-validate a customer’s basket at the checkout stage, before the order is completed. As the source of truth for item availability, pricing rules and tax calculation, the POS verifies each of these, so any issues can be flagged to the guest before payment is captured.
Format
The complete basket content is sent in the request body of a webhook event to a specified webhook endpoint. The order schema is the same as the Order Notification payload , with two additional top-level fields validationId and callbackUrl
Response
The POS is expected to validate the following;
- Confirmed Item availability
- Correct pricing
- Correct tax details
There are two methods of responding;
Synchronous validation
Return 200 OK with a JSON body containing the validation result. This is recommended where possible, so validation errors reach the guest straight away.
Asynchronous validation
Use this when validation requires a round trip to in-store systems and cannot complete within a few seconds.
Return 202 or a 200 with an empty body. Deliverect then marks the validation as pending and waits for a POST to the providedcallbackUrl ( see Validation Response Async )
Validation Errors
The response should include structured validation errors as shown in the Response section below which are relayed back to the ordering channel to surface any issues to the guest, for example to prompt them to adjust their cart as items are out of stock.
Once all corrections are applied and a customer completes checkout, an order would then be created and delivered to the POS Order Notification endpoint.
Inference rules
You can return a minimal response and let Deliverect infer the errors, see examples in the 200 response body below.
The rules are applied in order listed below:
| Rule | Applies when your response includes | Deliverect's result |
|---|---|---|
| Explicit errors | Entries in errors[] | Errors take precedence, so never set isValid: true while also reporting errors.See list of error codes here |
| Partial stock | items[] with available: false and quantity > 0 but below the requested quantity | quantity_unavailable |
| Full unavailability | items[] with available: false and quantity of 0 or omitted | product_snoozed |
| Price comparison | items[].price | Compared to the matching request line (by itemId, then plu). A difference over 1 cent returns price_mismatch. |
| Tax comparison | charges.tax or taxTotal | Compared to the request's taxTotal. A difference over 1 cent returns tax_mismatch. |
| De-duplication | Identical (code, path) pairs | Returned once only. |