If an order requires appeasement for any reason, that progress should begin with the Create Order Appeasement. This will allow the merchant to confirm details about who is responsible for the appeasement, how much credit they will pay, and other important information.
There are two cases in which this call is made; one in which a retailer pays the appeasement credit, and one in which a manufacturer pays the appeasement credit. The relevant case determines which of the below endpoint templates is used.
Note that the request body and parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.
| Production URL | https://{tenantId}-translation.mozu.com/api/v2/orderAppeasement/?orderID={orderId}&{retailerId_or_manufacturerId}={id} |
| Sandbox URL | https://{tenantId}-translation.sandbox.mozu.com/api/v2/orderAppeasement/?orderID={orderId}&{retailerId_or_manufacturerId}={id} |
| Supported Formats | JSON |
| HTTP Method | POST |
The ID of the order that this appeasement is being created for should be specified in the endpoint, by appending a “/?” to the call followed by the orderID. Following the orderID, either a retailerID or a manufacturerID should also be provided depending on which entity will be paying the credit. As explained later in this guide, this parameter must match the creditPayee in the request body as well as be provided again in the body.
- Retailer Call: https://{tenantId}-translation.mozu.com/api/v2/orderAppeasement/?orderID={orderId}&retailerID={retailerId}
- Manufacturer Call: https://{tenantId}-translation.mozu.com/api/v2/orderAppeasement/?orderID={orderId}&manufacturerId={manufacturerId}
Example
The example case creates an API call for an appeasement that has the following properties:
- $2 refund on Order 012345, paid by Manufacturer 543210
- From merchant’s catalog 0
- User ID 123456
This guide will demonstrate how to put together each section of the request to build this appeasement.
Required Parameters
The minimum required parameters are those that apply to the refund that will be awarded, specifically the person who will be paying it and the amount the customer will receive.
While the retailerID or manufacturerID is specified in the endpoint, it should still be provided in the body as well. Only one of these two parameters is required at a time, based on the appropriate creditPayee case – if a manufacturer is set as the payee but a retailerID is provided, then an error will be returned.
| Parameter | Type | Description |
| creditPayee | enum | The entity who will pay for the credit (this should be set to “MANUFACTURER” or “RETAILER”, unless otherwise advised by Kibo). |
| creditAmount | number | The amount to be credited. |
| creditDescription | string | The reason for the credit. |
| manufacterID | integer | A unique identifier for the manufacturer paying the credit. The minimum value is “0”. This parameter is required when creditPayee is set to “MANUFACTURER”. |
| retailerID | integer | A unique identifier for the retailer paying the credit. The minimum value is “0”. This parameter is only required when creditPayee is set to “RETAILER”. |
| rectifyOrder | boolean | Should the order be rectified? The default is “TRUE” so that even if this is not provided in the request, the parameter will be automatically set to the suggested best practice of rectification. |
Optional Parameters
Other possible parameters can be provided to specify other details about the appeasement. These variables are:
| Parameter | Type | Description |
| orderAppeasementID | integer | A unique identifier for the appeasement. This ID is set by OMS when created in the system, so it is best to treat it as read-only and not try to set this parameter. The minimum value is “1”. |
| orderID | integer | A unique identifier for the existing order that the appeasement is tied to; this must be specified in the endpoint but can also be included in the request body. The minimum value is “1”. |
| externalOrderID | string | A client-generated unique identifier for the order. |
| creditCreationTimestamp | string | The creation time of the credit. Supports date-time format. |
| catalogID | integer | The catalog number for the manufacturer. This is also a read-only parameter utilized by OMS internally. |
| emailConsumer | boolean | Indicates whether the consumer should be emailed when the credit is created. |
| userID | integer | A unique identifier for a user. The minimum value is “0”. |
| needToRectify | boolean | Whether rectification is appropriate for the order. This is a ready-only parameter, so do not attempt to set it – use rectifyOrder instead. |
| rectifyAmount | number | The amount to charge or refund for the order to be financially settled . |
The Full Request
This is the entire request that will create an appeasement for Order 012345. The order and manufacturer is identified in the endpoint:
https://{tenantId}-translation.mozu.com/api/v2/orderAppeasement/?orderID=012345&manufacturerID=543210The body of the request includes the basic appeasement information:
{
"creditPayee": "MANUFACTURER",
"creditAmount": 2,
"creditDescription": "No Inventory",
"manufacturerID": 543210,
"catalogID": 0,
"emailConsumer":true,
"userID":123456
}If this example were the case of a retailer payee instead of manufacturer, then the manufacturerID parameters in the above endpoint and body would be replaced by retailerID parameters instead.
The returned response follows the same structure as the Get Appeasement API, providing information about the appeasement that was created.