New order policy object to define the cancellation/return/cart_update/fulfillment_update/replacement policies #109
Description
Area
API
Working Groups
Core Specifications, Local Retail, Delivery
Contributor
Nirmal N R
Table of Contents
| No | Title |
|---|---|
| 1 | Current limitations |
| 2 | Solution approach |
| 3 | Use case example |
| 4 | Impact analysis |
Abstract
The order policy object will try to capture all the dimensions of what happens when the order is updated from the user end in a machine readable format.
The following dimensions of an order policy will be captured in the object :
- What sort of policy is being defined : cancellation, return, cart_update, fulfilment_update, replacement
- Policy definitions for separate order status/time windows (like from agent-assigned to order complete, 10 days after order completion etc)
- What will the action cost the user (is it a percentage of the cost of the item/order or fixed price)
- How much refund the customer will be entitled to (again is it a percentage of the cost of the item/order or fixed price)
- Is shipping service included for the action? If so, how much it will cost.
- Descriptor to describe the policy.
Contents
Current Limitations
Currently there is not method to send back the policy before the order is confirmed. The current policy object is just a descriptor object which describes the policy as sentences will not be machine readable.
Solution Approach
A new OrderPolicy object. This can be sent as a policies array on on_init.
OrderPolicy:
description: Describes an order related policy.
type: object
properties:
ref_object_id:
description: id of the object for which policy is defined. Can be left out for order
policy_type:
description: what type of policy is being defined
type: string
enum:
- cancellation
- return
- cart_update
- fulfillment_update
- replacement
policy_definitions:
description: Defining the policy for specific windows of the order status/time
type: array
items :
type: object
properties:
allowed:
description: if action is allowed or not
type: boolean
cancellation_reason_id:
type: string
time:
description: Describes time frame for which this policy definition applies to
type: object
properties:
from:
description: From what state of order/time this policy definition applies
type: object
properties:
order_state:
description: state refers to the state of the order and offset is an additional duration that can be given to add an extra amount of time after the order state.
type: object
properties:
state:
$ref: '#/components/schemas/Order/properties/state'
offset:
$ref: '#/components/schemas/Duration'
time:
$ref: '#/components/schemas/Time'
to:
description: Till what state of the order this policy definition applies
type: object
properties:
order_state:
description: state refers to the state of the order and offset is an additional duration that can be given to specify an amount of time after the order state.
type: object
properties:
state:
$ref: '#/components/schemas/Order/properties/state'
offset:
$ref: '#/components/schemas/Duration'
time:
$ref: '#/components/schemas/Time'
process_fees:
description: how much the customer will have to pay for the action
type: object
properties:
type:
description: whether it is a fixed amount payment or percentage of order/item value
type: string
enum:
- fixed
- percentage
price:
$ref: '#/components/schemas/Price'
percentage:
$ref: '#/components/schemas/DecimalValue'
refund_amount:
description: how much refund the customer is entitled to
type: object
properties:
type:
type: string
enum:
- fixed
- percentage
price:
$ref: '#/components/schemas/Price'
percentage:
$ref: '#/components/schemas/DecimalValue'
shipping_policy:
type: object
properties:
shipping_incl:
type: boolean
shipping_fees:
$ref: '#/components/schemas/Price'
policy_description:
$ref: '#/components/schemas/Descriptor'
Use case example
Consider if someone has the below cancellation policy :
- If cancellation reason is 'changed mind'
- before agent is assigned : no charge
- agent assigned to fulfillment complete : not allowed
- 48 hours after fulfillment complete : half refund
- beyond that : not allowed
- If cancellation reason is 'damaged goods'
- full refund
Then the below array can be sent in on_init to capture the same:
{
"policies": [
{
"policy_type": "cancellation",
"policy_definitions": [
{
"allowed": true,
"cancellation_reason_id": "changed_mind",
"time": {
"to": {
"order_state": {
"state": "agent-assigned"
}
}
},
"process_fees": {
"type": "fixed",
"price": {
"currency": "INR",
"value": "0"
}
},
"refund_amount": {
"type": "percentage",
"percentage": "100"
}
},
{
"allowed": false,
"cancellation_reason_id": "changed_mind",
"time": {
"from": {
"order_state": {
"state": "agent-assigned"
}
},
"to": {
"order_state": {
"state": "order-completed"
}
}
}
},
{
"allowed": true,
"cancellation_reason_id": "changed_mind",
"time": {
"from": {
"order_state": {
"state": "order-completed"
}
},
"to": {
"order_state": {
"state": "order-completed",
"offset": "P48H"
}
}
},
"process_fees": {
"type": "fixed",
"price": {
"currency": "INR",
"value": "0"
}
},
"refund_amount": {
"type": "percentage",
"percentage": "50"
}
},
{
"allowed": false,
"cancellation_reason_id": "changed_mind",
"time": {
"from": {
"order_state": {
"state": "order-completed",
"offset": "P48H"
}
}
}
},
{
"allowed": true,
"cancellation_reason_id": "damaged_goods",
"process_fees": {
"type": "fixed",
"price": {
"currency": "INR",
"value": "0"
}
},
"refund_amount": {
"type": "percentage",
"percentage": "100"
}
}
],
"policy_description": {
"name": "Cancellation Policy",
"long_desc": "In case the customer changed their mind before agent is assigned full refund will be provided with no charge. etc...."
}
}
]
}
Impact Analysis
This can be an optional object in the on_init call. The BPPs can choose to send just the policy_descriptor if they want to as well.