New order policy object to define the cancellation/return/cart_update/fulfillment_update/replacement policies

[techframewirk]

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 :

1. What sort of policy is being defined : cancellation, return, cart_update, fulfilment_update, replacement
2. Policy definitions for separate order status/time windows (like from agent-assigned to order complete, 10 days after order completion etc)
3. What will the action cost the user (is it a percentage of the cost of the item/order or fixed price)
4. How much refund the customer will be entitled to (again is it a percentage of the cost of the item/order or fixed price)
5. Is shipping service included for the action? If so, how much it will cost.
6. 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.