Order Return

An order or portion of an order is eligible for return only if it has been fulfilled and the items to be returned have not previously been returned. Even if it meets these conditions, the order may not be returnable, or individual items may not be returnable if an item’s eligible property is set to false in check order return eligibility API response, or if fabric OMS determines an item cannot be returned.

General Rules:

• Return for an item is identified by the exchange boolean (exchange is set to false) field on the return payload.
• Return for an order is validated for eligibility based on the orderId and lineItemId.
• Charged amount in the payments object of the order document should not be null to process the refund.
• Use POST/api/v2/order/return endpoint to initiate order-return.
• Order status should be one of: ORDER_DELIVERED, ORDER_SHIPPED, ORDER_PARTIALLY_SHIPPED, ORDER_PARTIALLY_DELIVERED, ORDER_PARTIALLY_RETURNED,
  ORDER_PARTIALLY_CANCELLED, PICKUP_COMPLETE.
• lineOrderStatus should be one of: PENDING_EXCHANGE,RETURN_PROCESSING, PARTIALLY_CANCELLED, PARTIALLY_REFUNDED,PARTIALLY_CANCELLED_REFUNDED,VALID, PENDING_RETURN, ORDER_LINE_VALID, SHIPPED, PARTIALLY_SHIPPED, PARTIALLY_ALLOCATED, DELIVERED, PARTIALLY_DELIVERED, PARTIAL_RETURN.

Return Workflow

• Item reaches distribution center and is processed for return or reject
  • Create a return when an item is received or accepted for return

Create return when an item is pending to be received at the distribution center

• When a shopper or a customer service agent creates a return request, but the item is not received at the distribution center: Set returnType to PENDING in the request payload while calling POST/api/v2/order/return to create a return.
• lineOrderStatus will be updated to RETURN_PENDING for the line item of an order ID. You can get the order details, along with the order status, by calling the GET/api/v2/order endpoint.
• RETURN_PENDING webhook event is triggered if the merchant has subscribed to the event. The target URL of the subscription payload is notified.

sample curl

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: MERCHANT_ACCOUNT_ID' \
--header 'x-site-context: {"stage":"sandbox","account":"MERCHANT_ACCOUNT_ID","date":"2022-11-24T10:36:54.603Z","channel":"12"}' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "635c2f5f126dc62ebf3b28f4",
    "returnTimeStamp": "2022-07-11T15:03:14.642Z",
    "employeeId": "8a7465",
    "source": "CSR",
    "exchange": false, // when request is exchange, it will be true
    "totalRefundAmount": 96
    "refunds": [

        {
            "type": "SHIPPING"
            "name": "SHIPPING_FEE"
            "value": 3
        }
    ],
    "fees": [

        "type": "FEE"
        "name": "RETURN_FEE"
        "value": 7
    ],
    "items": [
        {
            "orderLineItemId": "{{orderLineItemId}}",
            "shipmentId": "12345-PS",
            "shipmentLineId": "1",
            "returnType": "PENDING",
            "quantity": 1,
            "scanTimeStamp": "2022-07-11T15:03:14.642Z",
            "reasonCode": "reasonCode",
            "subReasonCode": "subReasonCode",
            "policyOveride": true,
            "returnAmount": 96,
            "refunds": [
                {
                    "type": "ITEM",
                    "name": "SUBTOTAL",
                    "value": 88.79
                },
                {
                    "type": "TAX",
                    "name": "CITY",
                    "value": 2.18
                },
                {
                    "type": "TAX",
                    "name": "STATE",
                    "value": 1.59
                },
                {
                    "type": "TAX",
                    "name": "OTHER",
                    "value": 6.44
                }
            ],
            "fees": [
                {
                    "type": "GIFT_WRAPPING",
                    "name": "WRAP_FEE",
                    "value": 3
                }
            ],
		"exchange": {}
        }],
        "attributes": {
		"fraudStatus": "FRAUD_PASS",
		"fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0",
		"fraudCheckStatus": "UPDATED",
		"fraudCheckTransId": "K95X0B1RBKYN",
		"additionalProp1": {}
	}
}

Item reaches distribution center and is processed for return or reject

• When an item reaches the distribution center, use POST/api/v2/order/return endpoint to set returnType to PROCESSING in the request payload.
• lineOrderStatus will be updated to RETURN_PROCESSING for the line item of the order ID. You can get the order details, along with the order status, by calling the GET/api/v2/order endpoint.
• At this stage, the customer service agent at the warehouse or the distribution center does the quality checks such as, if the item is in good condition to return if the item matches the original order, etc. After a thorough inspection, the CSR can accept or reject the return request.
• RETURN_PROCESSING webhook event is triggered if the merchant has subscribed to the event. The target URL of the subscription payload is notified about the event.

sample curl:

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: MERCHANT_ACCOUNT_ID' \
--header 'x-site-context: {"stage":"sandbox","account":"MERCHANT_ACCOUNT_ID","date":"2022-11-24T10:36:54.603Z","channel":"12"}' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "635c2f5f126dc62ebf3b28f4",
    "returnTimeStamp": "2022-07-11T15:03:14.642Z",
    "employeeId": "8a7465",
    "source": "CSR",
    "exchange": false, // when the request is ‘exchange’, it will be true
    "totalRefundAmount": 96
    "refunds": [
        {
            "type": "SHIPPING"
            "name": "SHIPPING_FEE"
            "value": 3
        }
    ],
    "fees": [
        "type": "FEE"
        "name": "RETURN_FEE"
        "value": 7
    ],
    "items": [
        {
            "orderLineItemId": "{{orderLineItemId}}",
            "shipmentId": "12345-PS",
            "shipmentLineId": "1",
            "returnType": "PROCESSING",
            "quantity": 1,
            "scanTimeStamp": "2022-07-11T15:03:14.642Z",
            "reasonCode": "reasonCode",
            "subReasonCode": "subReasonCode",
            "policyOveride": true,
            "returnAmount": 96,
            "refunds": [
                {
                    "type": "ITEM",
                    "name": "SUBTOTAL",
                    "value": 88.79
                },
                {
                    "type": "TAX",
                    "name": "CITY",
                    "value": 2.18
                },
                {
                    "type": "TAX",
                    "name": "STATE",
                    "value": 1.59
                },
                {
                    "type": "TAX",
                    "name": "OTHER",
                    "value": 6.44
                }
            ],
            "fees": [
                {
                    "type": "GIFT_WRAPPING",
                    "name": "WRAP_FEE",
                    "value": 3
                }
            ],
		"exchange": {}
        }],
        "attributes": {
		"fraudStatus": "FRAUD_PASS",
		"fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0",
		"fraudCheckStatus": "UPDATED",
		"fraudCheckTransId": "K95X0B1RBKYN",
		"additionalProp1": {}
	}
}

• If customer service agents reject the return request for any reason, they must use POST/api/v2/order/return endpoint to set returnType to REJECTED.
• Provide proper reason and sub-reasons for rejecting the return request.
• lineOrderStatus is updated to RETURN_REJECTED for the line item of the order ID. You can get the order details, along with the order status, by calling the GET/api/v2/order endpoint.
• RETURN_REJECTED webhook event is triggered if the merchant has subscribed to the event. The target URL will be notified of the event.

sample curl:

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: MERCHANT_ACCOUNT_ID' \
--header 'x-site-context: {"stage":"sandbox","account":"MERCHANT_ACCOUNT_ID","date":"2022-11-24T10:36:54.603Z","channel":"12"}' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "635c2f5f126dc62ebf3b28f4",
    "returnTimeStamp": "2022-07-11T15:03:14.642Z",
    "employeeId": "8a7465",
    "source": "CSR",
    "exchange": false, // when request is exchange, it will be true
    "totalRefundAmount": 96
    "refunds": [

        {
            "type": "SHIPPING"
            "name": "SHIPPING_FEE"
            "value": 3
        }
    ],
    "fees": [

        "type": "FEE"
        "name": "RETURN_FEE"
        "value": 7
    ],
    "items": [
        {
            "orderLineItemId": "{{orderLineItemId}}",
            "shipmentId": "12345-PS",
            "shipmentLineId": "1",
            "returnType": "REJECTED",
            "quantity": 1,
            "scanTimeStamp": "2022-07-11T15:03:14.642Z",
            "reasonCode": "reasonCode",
            "subReasonCode": "subReasonCode",
            "policyOveride": true,
            "returnAmount": 96,
            "refunds": [
                {
                    "type": "ITEM",
                    "name": "SUBTOTAL",
                    "value": 88.79
                },
                {
                    "type": "TAX",
                    "name": "CITY",
                    "value": 2.18
                },
                {
                    "type": "TAX",
                    "name": "STATE",
                    "value": 1.59
                },
                {
                    "type": "TAX",
                    "name": "OTHER",
                    "value": 6.44
                }
            ],
            "fees": [
                {
                    "type": "GIFT_WRAPPING",
                    "name": "WRAP_FEE",
                    "value": 3
                }
            ],
		"exchange": {}
        }],
        "attributes": {
		"fraudStatus": "FRAUD_PASS",
		"fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0",
		"fraudCheckStatus": "UPDATED",
		"fraudCheckTransId": "K95X0B1RBKYN",
		"additionalProp1": {}
	}
}

Create a return when an item is received or accepted for return

• Use POST/api/v2/order/return endpoint, and set returnType to received.
• The amount received for return will be validated based on the invoiced amount for the item. If validation fails for any reason, an error message will be returned.
• If a refund for returned item is successful, the response for the order return endpoint (POST/api/v2/order/return) will display refundStatus as SUCCESSFUL.
• If all the quantity of line items are returned:
  • lineOrderStatus (return status at item level) will be updated to RETURNED.
  • statusCode (return status at order level) will be updated to ORDER_RETURNED.
• If some of the quantities of line items are returned:
  • lineOrderStatus (return status at item level) will be updated to PARTIALLY_RETURNED.
  • statusCode (return status at order level) will be updated to ORDER_PARTIALLY_RETURNED.
• If the refund failed for any reason, the response for the order return endpoint (POST/api/v2/order/return) will display refundStatus as REFUND_FAILED.
• RETURN_NOTIFICATION_EMAIL and REFUND_NOTIFICATION_EMAIL webhook events are triggered if the merchant has subscribed to the events, and details are sent to the merchant.

sample curl:

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: MERCHANT_ACCOUNT_ID' \
--header 'x-site-context: {"stage":"sandbox","account":"MERCHANT_ACCOUNT_ID","date":"2022-11-24T10:36:54.603Z","channel":"12"}' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderId": "635c2f5f126dc62ebf3b28f4",
    "returnTimeStamp": "2022-07-11T15:03:14.642Z",
    "employeeId": "8a7465",
    "source": "CSR",
    "exchange": false, // when the request is ‘exchange’, it will be true
    "totalRefundAmount": 96
    "refunds": [
        {
            "type": "SHIPPING"
            "name": "SHIPPING_FEE"
            "value": 3
        }
    ],
    "fees": [
        "type": "FEE"
        "name": "RETURN_FEE"
        "value": 7
    ],
    "items": [
        {
            "orderLineItemId": "{{orderLineItemId}}",
            "shipmentId": "12345-PS",
            "shipmentLineId": "1",
            "returnType": "RECEIVED",
            "quantity": 1,
            "scanTimeStamp": "2022-07-11T15:03:14.642Z",
            "reasonCode": "reasonCode",
            "subReasonCode": "subReasonCode",
            "policyOveride": true,
            "returnAmount": 96,
            "refunds": [
                {
                    "type": "ITEM",
                    "name": "SUBTOTAL",
                    "value": 88.79
                },
                {
                    "type": "TAX",
                    "name": "CITY",
                    "value": 2.18
                },
                {
                    "type": "TAX",
                    "name": "STATE",
                    "value": 1.59
                },
                {
                    "type": "TAX",
                    "name": "OTHER",
                    "value": 6.44
                }
            ],
            "fees": [
                {
                    "type": "GIFT_WRAPPING",
                    "name": "WRAP_FEE",
                    "value": 3
                }
            ],
		"exchange": {}
        }],
        "attributes": {
		"fraudStatus": "FRAUD_PASS",
		"fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0",
		"fraudCheckStatus": "UPDATED",
		"fraudCheckTransId": "K95X0B1RBKYN",
		"additionalProp1": {}
	}
}