Skip to main content

Cancellations & Refunds

Orders/Orders/Order No: 123123123 should be canceled on the Omnitron’s left sidebar menu.

The detail page is reached by selecting the order to be processed as stated before. Cancellations related to the order can be made on the detail page.

Process​

During the cancellation process, the cancel_status value of the order is checked. If the Cancel_status field is CancelStatus.approved, an OrderUpdateCancelStatusException error will occur when trying to change it from this status to the CancelStatus.confirmed status. If the Cancel_status field is CancelStatus.waiting_for_payment, trying to switch to the following statuses [waiting,confirmation_waiting,confirmed,approved,rejected] OrderUpdateCancelStatusException error will occur. If the value is CancelStatus.waiting, a OrderCancelMoreThenOneException is thrown. A check is performed to determine whether the is_all value is True, and the cancel_items array is full. A check is performed to determine whether the is_cargo_refund value is True, and the cancel_items or is_all value is True. In case of an error, an OrderCancelOverlappingParameterException is issued.

The canceled product objects are checked for value reasons. In case of an error, an OrderCancelMissingReasonException is issued.

The payment options of the order are checked. If the payment type is credit card, the payment transactions are checked and the order payment amount is calculated. If the payment type is not a credit card, the order amount is taken from the order object. If the Payment_option field is PaymentType.credit_card, a payment record is expected. If not, an OrderCancelPurchaseTransactionNotFound error occurs. If the refund amount is less than 0, an OrderCancelNoRefundableAmountException error occurs. If the Payment_option field is PaymentType.pay_on_delivery, the products in the order are checked. If there are order items belonging to different statuses, an OrderCancelMultipleItemStatusException error occurs. Forced_refund control is performed on order items. If this field is active, forced_refund_amount is expected to be delivered, OrderCancelManuallyException error occurs in undelivered transactions.

An OrderCancelMoreThenOneException error occurs if there is a product with the status CancelStatus.waiting, CancelStatus.approved or CancelStatus.manuel_refund_need among the order items.

OrderCancelItemsIsNotConsistent error occurs when order items that are to be canceled are delivered, and an item that does not exist on the order is transmitted.

OrderCancelItemMultipleDataSourcesFoundException error occurs when order items have more than one supplier.

​​Cancellation or refund can be made at the same time during the transaction. In this case, requests must be submitted separately. If they are submitted together, a CancelOrderItemMixedException error occurs.

The can_be_sent_to_erp value is checked for status approval during the order process.

The payment options of the order are checked. If the payment type is credit card, the payment transactions are checked and the order payment amount is calculated. If the payment type is not a credit card, the order amount is taken from the order object.

If the cancel_status of the products in the order is [CancelStatus.waiting,CancelStatus approved or CancelStatus.manuel_refund_need], an OrderCancelMoreThenOneException is sent.

If the order contains an invoice_number, the cancellation_type will be a refund; if not, it will be cancellation.

If there is a forced_refund_amount, the refund is made with the forced_refund_amount value. If not, it is calculated with the calculate_refund function according to the strategy selected in the settings.

The CancellationPlan object is created depending on the order status. If the created CancellationPlan status is confirmation_waiting, the order cancellation process is completed with the use of the approve or reject buttons on the Front-End.

If the orders are linked to customers" ERP systems, approval is assessed using the approved_order_cancel function to obtain approval from the ERP system, and the process is completed by changing the cancellation status of the order.

Statuses​

The statuses for the stages of the order cancellation process are provided below.

omnicore.orders.enums.CancelStatus​

The values ​​that the cancel_status field that the order can take. Indicates at what stage the cancellation process is on the order.

  • waiting,
  • confirmation_waiting,
  • confirmed, approved,
  • rejected,
  • waiting_for_payment,
  • manuel_refund_need,
  • completed

omnicore.orders.enums.CancellationType​

Indicates whether the operation is canceled or refunded on CancellationRequest.

  • cancel
  • refund

omnicore.orders.enums.CancellationRequestStatus​

Indicates the stage of the CancellationRequest values ​​that occur with the cancellation request.

  • OPEN,
  • WAITING,
  • CONFIRMATION_WAITING,
  • CONFIRMED,
  • WAITING_APPROVAL,
  • APPROVED,
  • REJECTED,
  • WAITING_FOR_PAYMENT,
  • MANUEL_REFUND_NEED,
  • COMPLETED

omnicore.orders.enums.OrderStatus​

It is stored in the status field on the order and indicates the current stage.

  • cancellation_waiting,
  • cancelled, waiting,
  • payment_waiting,
  • confirmation_waiting,
  • approved, preparing,
  • shipped,
  • shipped_and_informed,
  • ready_for_pickup,
  • attempted_delivery,
  • review_started,
  • review_waiting,
  • delivered,
  • refunded

POST Create Cancellation Request​

Path: /api/v1/orders/{order_pk}/cancel/

{
"order": "<order_pk>",
"is_all": false,
"reasons": {'35': 1},
"forced_refund_amount": "13,12",
"cancel_items": [35,12],
"refund_invoice_number":"123213",
"is_cargo_refund":false,
"retail_store_remote_id":"12",
"staff_remote_id":"1",
"return_details":false
}

Response / 200

return_details == False     
    {"success": True}      

return_details == True      
    OrderDetailedSerializer.data

Response / 400

{"order": [u"Invalid pk "123" – object does not exist."]}

Response / 406

     {"non_field_errors": u"Order cancel is not valid", "error_code": u"cancel_100"}

Viewset​

Employs the cancel method of the omnitron.orders.resources.views.OrderViewSet Class. With the request, this part is triggered and the cancellation process of the order will start.

Service​

Employs the cancel method of the omnitron.orders.service.OrderService Class. When the cancellation request is sent, the process will be transmitted with the following service. The parameters received by the service and the return value are listed.

Service name: cancel_order

Received parameters :

  • order
  • reasons
  • is_all
  • cancel_items
  • forced_refund_amount
  • is_cargo_refund
  • refund_invoice_number
  • next_status
  • ibans
  • holder_names

Return value: Order

Used Methods​

CancellationStrategy
omnitron.orders.service.OrderService._create_cancellation_request
omnitron.orders.service.OrderService._validate_cancellation_info
omnitron.orders.service.OrderService._create_cancellation_plan
omnitron.orders.service.OrderService.approved_order_cancel

Strategy​

During the cancellation process of the order, the CANCELLATION_STRATEGY variable in the settings.py file defines the strategies from StrategyOne to StrategyEleven in the strategy.py file on a company basis. Strategy classes are essentially derived from the omnitron.orders.strategies.CancellationStrategy class.

Serializer​

OrderCancelSerializer: Controls the parameters and structures that can make the request thrown to initiate the cancellation process.

NameDescription
orderOrders with statuses other than [cancelled, refunded, cancellation_waiting]
is_all
  • boolean
  • Default:False
  • Used to cancel all products.
  • If true, the cancel_items value must be an empty array.
cancel_itemsThe order_item list to be canceled.
forced_refund_amount
  • Decimal
  • allow_null=True
  • The field for entering the refund amount optionally
reasons
  • DictField
  • {order_item_id : CancellationReason}
  • Cancellation reason
is_cargo_refund
  • boolean
  • required=False
  • Cargo refund
refund_invoice_number
  • CharField
  • required=False, default=None
  • Refund invoice number
ibans
  • DictField
  • required=False
holder_name
  • DictField
  • required=False

POST Reject Cancellation Request​

Path: /api/v1/orders/{order_pk}/cancellation_reject_order/

The method that permits the rejection of the order cancellation process.

Response / 200

  OrderDetailedSerializer.data

Response / 404

{
    "detail": "Not found."
}

Service​

reject_order_cancel method of the omnitron.orders.service.OrderService class is used.

Service name: reject_order_cancel

Received parameter: order

Return Value: order

Used Methods​

omnitron.orders.service.OrderService._update_cancellation_request
omnitron.orders.service.OrderService.update_cancellation_plan

POST Approve Cancellation Request​

Path:/api/v1/orders/{order_pk}/cancellation_approved_order/

The method that permits the approval of the order cancellation process.

{
"invoice_number":"1321213123"
}

Response / 200

OrderDetailedSerializer.data

Service​

approved_order_cancel method of the omnitron.orders.service.OrderService class is used.

Service name: approved_order_cancel

Received parameters:

  • order
  • invoice_number
  • payment_plan

Return value: order

Used Methods​

omnitron.orders.service.OrderService._update_cancellation_request
omnitron.orders.service.OrderService.update_cancellation_plan

Serializer​

Controls the parameters and structures of the requester thrown to confirm the cancellation.

omnitron.orders.resources.serializers.CancellationApprovedOrderSerializer

  • invoice_number:
    • CharField
    • Default: None
    • Invoice number
  • payment_plan
    • JsonField
    • required=False

Cancellation Status​

It is used to update the cancel_status fields of orders and order items whose cancellation process has been initiated.

POST Update Cancellation Status​

Path: /api/v1/orders/{order_pk}/update_cancel_status/

Request

{
"cancel_status": "manuel_refund_need",
"order": 45,
"order_items": [118]
}

Response / 200

OrderDetailedSerializer.data

Serializer​

CancelStatusUpdateSerializer: Controls the requesting parameters and structures to update status on cancellation.

  • order:
    • Order
  • order_items:
    • ListField
    • required=False
    • OrderItem
  • cancel_status:
    • omnicore.orders.enums.CancelStatus (Values ​​in the Status section)

Cancellation Requests​

The method that permits the creation of cancellation requests. Used for the products in the order. GET, POST, PUT and DELETE features are used.

GET Cancellation Requests​

Path: /api/v1/cancellation_requests/

Response

{
    "count": 13,
    "next": "{customer_omnitron_url}/api/v1/cancellation_requests/?page=4",
    "previous": "{customer_omnitron_url}/api/v1/cancellation_requests/?page=2",
    "results": [
        {
            "id": 5,
            "cancellation_type": "refund",
            "status": "open",
            "easy_return": 1,
            "created_date": "2021-06-03T07:25:24.520026Z",
            "modified_date": "2021-06-03T07:25:24.520106Z",
            "uuid": "abcacaec-9644-408b-9b45-ce96847a5d90",
            "description": "Description",
            "iban": "TRXXXXX10009999901234567890",
            "holder_name": "Courier Company Name",
            "reason": 2,
            "order_item": 416
           },..]
}

GET Cancellation Request Detail​

Path: /api/v1/cancellation_requests/{id}/

Response

{
  "id": 5,
  "cancellation_type": "refund",
  "status": "open",
  "easy_return": "1",
  "created_date": "2021-06-03T07:25:24.520026Z",
  "modified_date": "2021-06-03T07:25:24.520106Z",
  "uuid": "abcacaec-9644-408b-9b45-ce96847a5d90",
  "description": "Description",
  "iban": "TR320010009999901234567890",
  "holder_name": "Courier Company Name",
  "reason": 2,
  "order_item": 416
}

PUT Update Cancellation Request​

Path: /api/v1/cancellation_requests/{id}/

{
    "id": 5,
    "cancellation_type": "refund",
    "status": "open",
    "easy_return": 1,
    "created_date": "2021-06-03T07:25:24.520026Z",
    "modified_date": "2021-06-03T07:25:24.520106Z",
    "uuid": "abcacaec-9644-408b-9b45-ce96847a5d90",
    "description": "Description",
    "iban": "TR320010009999901234567890",
    "holder_name": "Courier Company Name",
    "reason":1,
    "order_item": 416
}

Response

{
    "id": 5,
    "cancellation_type": "refund",
    "status": "open",
    "easy_return": 1,
    "created_date": "2021-06-03T07:25:24.520026Z",
    "modified_date": "2021-06-03T07:25:24.520106Z",
    "uuid": "abcacaec-9644-408b-9b45-ce96847a5d90",
    "description": "Description",
    "iban": "TR320010009999901234567890",
    "holder_name": "Courier Company Name",
    "reason": 1,
    "order_item": 416
}

POST Create Cancellation Request​

Path: /api/v1/cancellation_requests/

{
  "order_item": 116,
  "cancellation_type": "refund",
  "reason": 1
}

Response

HTTP200

DELETE Cancellation Request​

Path: /api/v1/cancellation_requests/{id}/

Response

HTTP204

Viewset​

Uses the omnitron.orders.resources.views.CancellationRequestViewSet class. ViewSet handles requests for CancellationRequest transactions. After the controls are made, the service is triggered to perform the transaction.

Serializer​

omnitron.orders.resources.serializers.CancellationRequestSerializer

Controls the parameters and their structures in requests to the Viewset.

NameDescription
Id =IntegerField(label="ID", read_only=True)
cancellation_type =EnumField(enum_type=<enum "CancellationType">)
status =EnumField(enum_type=<enum "CancellationRequestStatus">, read_only=True)
easy_return =
  • CancellationEasyReturnSerializer(read_only=True): Easy cancellation model
  • id = IntegerField(label="ID", read_only=True)
  • status = EnumField(enum_type=<enum "CancellationEasyReturnStatus">, read_only=True)
  • shipping_company = EnumField(enum_type=<enum "ShippingCompany">, read_only=True)
  • created_date = DateTimeField(read_only=True)
  • modified_date = DateTimeField(read_only=True)
  • uuid = UUIDField(required=False, validators=[<UniqueValidator(queryset=CancellationEasyReturn.objects.all())>])
  • code = CharField(max_length=64, validators=[<UniqueValidator(queryset=CancellationEasyReturn.objects.all())>])
  • start_date = DateTimeField(allow_null=True, required=False)
  • end_date = DateTimeField(allow_null=True, required=False)
  • max_count = IntegerField(allow_null=True, max_value=2147483647, min_value=0, required=False)
  • raw_request = CharField(style={"base_template": "textarea.html"})
  • raw_response = CharField(style={"base_template": "textarea.html"})
created_date =DateTimeField(read_only=True)
modified_date =DateTimeField(read_only=True)
uuid =UUIDField(required=False, validators=[<UniqueValidator(queryset=CancellationRequest.objects.all())>])
description =CharField(allow_blank=True, allow_null=True, required=False, style={"base_template": "textarea.html"})
iban =CharField(allow_blank=True, allow_null=True, max_length=34, required=False)
holder_name =CharField(allow_blank=True, allow_null=True, max_length=255, required=False)
reason =PrimaryKeyRelatedField(queryset=CancellationReason.objects.all())
order_item =PrimaryKeyRelatedField(queryset=OrderItem.objects.all(), validators=[<UniqueValidator(queryset=CancellationRequest.objects.all())>])

Service​

omnitron.orders.service CancellationRequestApprovalService.create_cancellation_request method is used.

Service name: create_cancellation_request

Received parameters:

  • order_item
  • cancellation_type
  • reason
  • iban
  • holder_name
  • description

Return value: cancellation_request

Cancellation Reasons​

The class for CREATING, UPDATING and DELETING the selected cancellation reasons during the cancellation process.

GET Cancellation Reasons​

Path: /api/v1/cancellation_reasons/

Response

{
    "count": 11,
    "next": "{customer_omnitron_url}/api/v1/cancellation_reasons/?page=4",
    "previous": "{customer_omnitron_url}/api/v1/cancellation_reasons/?page=2",
    "results": [
        {
            "pk": 1,
            "cancellation_type": "cancel",
            "extra_information_needed": false,
            "order": 100,
            "subject": "I bought wrong product.",
            "is_active": true,
            "send_to_remote": false
        },…]
}

POST Create Cancellation Reason​

Path: /api/v1/cancellation_reasons/

{
    "cancellation_type": "refund",
    "extra_information_needed": true,
    "order": 100,
    "subject": "Cancellation Reason",
    "is_active": true,
    "send_to_remote": false
}

Response

{
    "pk": 11,
    "cancellation_type": "refund",
    "extra_information_needed": true,
    "order": 100,
    "subject": "Cancellation Reason",
    "is_active": true,
    "send_to_remote": false
}

PUT Update Cancellation Reason​

Path: /api/v1/cancellation_reasons/{id}/

{
    "cancellation_type": "refund",
    "extra_information_needed": true,
    "order": 100,
    "subject": "Another Cancellation Reason",
    "is_active": true,
    "send_to_remote": false
}

Response 

{
    "pk": 11,
    "cancellation_type": "refund",
    "extra_information_needed": true,
    "order": 100,
    "subject": "Another Cancellation Reason",
    "is_active": true,
    "send_to_remote": false
}

DELETE Cancellation Reason​

Path: /api/v1/cancellation_reasons/{id}/

Response

HTTP204

Viewset​

Uses the omnitron.orders.resources.views.CancellationReasonViewSet class. ViewSet meets requests for cancellation responses. After the controls are made, the service is triggered to perform the transaction.

Serializer​

omnitron.orders.resources.serializers.CancellationReasonSerializer: Controls the parameters and their structures in requests to the ViewSet.

NameDescription
pk =IntegerField(label="ID", read_only=True)
cancellation_type =EnumField(enum_type=<enum "CancellationType">)
extra_information_needed =BooleanField(required=False)
order =IntegerField(max_value=2147483647, min_value=0, required=False)
subject =CharField(max_length=100)
is_active =BooleanField(required=False)
send_to_remote =BooleanField(required=False)

Service​

The omnitron.orders.service.CancellationReasonService class is derived from the omnicore.orders.service.BaseCancellationReasonService class. Adding, deleting and updating transactions are done through the Services.

Service name: create_cancellation_reason

Received parameters:

  • subject
  • cancellation_type
  • extra_information_needed(default=False)
  • order(default=100)

Return value: CancellationReason

Service name: update_cancellation_reason

Received parameters:

  • instance
  • subject(default=None)

Return value: instance

Service name: delete_cancellation_reason

Received parameters: instance

Cancellation Plans​

The cancellation_plan is created when the cancellation process is started for the order. It is used to update the status of the CancellationPlan record.

GET Cancellation Plan Statuses​

Path: /api/v1/cancellation_plans/cancellation_plan_statuses/

Response

{
    "cancellation_plan_statuses": {
        "confirmed": "Confirmed",
        "manuel_refund_need": "Manuel Refund Need",
        "completed": "Completed",
        "confirmation_waiting": "Confirmation Waiting",
        "rejected": "Rejected",
        "failed": "Failed",
        "waiting": "Waiting",
        "cancelled": "Cancelled",
        "waiting_for_payment": "Waiting For Payment",
        "approved": "Approved"
    }
}

POST Update Cancellation Plan Status​

Path: /api/v1/cancellation_plans/{pk}/update_status/

{
    "order":32,
    "status": "waiting"
}

Response

HTTP200

Viewset​

Uses the omnitron.orders.resources.views.CancellationPlanViewSet class. Derived from rest_framework.viewsets.ReadOnlyModelViewSet and omnitron.channels.resources.views.IntegrationMappingMixin classes.

CancellationPlan records allow services to be triggered by responding to status update or current status requests.

Serializer​

omnitron.orders.resources.serializers.CancellationPlanSerializer: Controls parameters and structures in delivered requests.

NameDescription
order =OrderSerializer()
order_previous_status =EnumField(enum_type=OrderStatus)
status =EnumField(enum_type=CancellationPlanStatus)
plan_type =EnumField(enum_type=CancellationPlanType)
cancellationplanorderitem_set =CancellationPlanOrderItemSerializer( many=True, read_only=True)
invoice_number =serializers.CharField(required=False)
created_by =UserSerializer()
last_updated_by =serializers.SerializerMethodField()

Service​

Uses the omnitron.orders.service.CancellationPlanService class. Contains the status update service triggered by the View.

Service name: update_status

Received parameters:

  • instance
  • Status

Return value: instance