Technical guide - Appeasements
Prerequisites
While the feature can be technically activated manually, specific prerequisites must be met to ensure accurate calculation of "appeasable" amounts.
Accuracy Disclaimer: If these prerequisites are not met, the feature remains functional, but OneStock cannot guarantee the precision of the refund calculations.
Core Requirements
Requirement | Required for |
Payment V2 Integration | Orders where OneStock manages payment. |
Taxes managed in “included_in_price” | Orders subject to tax calculations. |
Data Model : Discounted-Price-Secretary (DPS)
Database Architecture
The DPS service manages its own dedicated database to ensure strict isolation and high availability of appeasement data. This allows for a clean separation between core order processing and financial adjustments.
Schema: appeasements Table
We have introduced a central table to track every appeasement. Each record is designed to provide a full audit trail of why and how a price adjustment was made.
API Routes
The DPS service exposes three main endpoints to manage the lifecycle of an appeasement:
POST /appeasements: Creates a new record. This endpoint triggers the validation logic to ensure the requested amount is acceptable. api documentation - internal onlyNB : the creation of an appeasement automaticcally send a webhook. More information
GET /appeasements/{id}: Retrieves an appeasement with its specific id. This is crucial for calculating the "Remaining Appeasable Amount" ensuring we never refund more than the original price of the order. api documentation - internal onlyPOST /appeasements/query: An advanced search endpoint. It allows for complex filtering (by creation_date or order_ids) and is designed to handle large volumes of data efficiently. api documentation - internal only
Validation & Price Calculation
To maintain financial integrity, the service performs a real-time check before approving any new request
Formula :
Maximum appeasment amount =
order.princing_details.price- Sum(appeasment.amount)
The system will reject any POST /appeasements request where the requested amount is greater than the Remaining Balance.
Webhook & Event Integration
To ensure seamless synchronization with external systems (such as ERPs, CRMs like Salesforce, or BI tools), OneStock triggers a specific event every time an appeasement is generated in the Order Management System.
Topic: appeasement_created
The webhook is dispatched as soon as a Customer Service operator confirms the appeasement in the Back Office, regardless of whether the payment capture has occurred yet.
Payload Overview
The event payload contains all the necessary metadata to track the refund context and origin:
order_id: string
parent_order_id: string
amount: float
currency: stringorder_id : order related to the appeasement
parent_order_id : parent order related to the appeasement
amount : monetary value of the appeasement
currency : currency of the appeasement
sales channels : sales channel of the order related to the appeasement