General Rules:

  • Exchange functionality does not have a separate endpoint to be called, and uses the return service (endpoint) for performing order exchanges.
  • Exchange for an item is identified by the exchange boolean field on the return payload.
  • For an exchange, if the item cannot be shipped due to being out of stock, but the item returned for the exchange is processed, then the amount for the line item quantities (that were returned) must be refunded.
  • Refunding and payment due to the price difference between the original and replacement items are not handled by the returns or exchange service. This information must be sent by the requester during the pending return flow.

The exchange functionality in Order Management System (OMS) lets Customer Service Representatives (CSR) exchange an order item. Exchange is essentially a return + a new item shipment, and this phase integrates the returns service with the exchange service.

Workflow:

The exchange functionality has two flows:

​
Exchange items are shipped when the return is received

  • returnType is flagged as Received
  • exchange is flagged true
  • initiateReshipment is flagged true for items
  • The returns service gets a “PENDING” return request flagged as an exchange.
  • The returns service notifies the exchange service about the exchange.
  • The exchange service broadcasts that the exchange is pending.
  • The returns service gets a “RECEIVED” return request.
  • The exchange service updates the order document by changing the status of the replacement item to be shipped.
  • The exchange service broadcasts that the exchange is sent to the Shipment service.
  • Allocation service handles inventory updates and shipping.
  • If the client POSTs the return received, then:
    • ship the new item
    • disable refunding for the original item
  • If the client initiates an exchange for a pending return, then the network inventory is reserved at the time the exchange is created. From there, fabric OMS awaits until the item returnType “RECEIVED” is posted by the client. If the client receives the item to be returned then,
    • ship the new item
    • disable refunding for the original item

sample curl:

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: YOUR_ACCOUNT_ID_HERE' \
--header 'x-site-context: {"stage":"sandbox","account":"YOUR_ACCOUNT_ID_HERE","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": true,
    "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": 100.00,
            "fees": [
                {
                    "type": "tax",
                    "value": 34.56,
                    "quantity": 1,
                    "refundAmount": 10.4
                }
            ],
            "exchange": {
                "disableRefunding": true,
                "payment": {},
                "refund": {},
                "items": [
                    {
                        "itemId": "itemid-1",
                        "sku": "451009965461",
                        "itemUnitPrice": 0.00,
                        "quantity": 1,
                        "initiateReshipment": true
                    }
                ]
            }
        }
    ],

​
Exchange items are shipped irrespective of the item being received

  • Exchange for an item is identified by the exchange boolean field on the return payload.
  • The requester sets initiateReshipment to true at the first moment of the exchange, indicating the immediate shipping of the replacement item regardless of the return status (received or pending). In this case, the allocation service will be triggered at the end of the pending return flow.
  • Admin ships the new item without the distribution center receiving the item, and disables refunding for the original item.

sample curl:

curl --location --request POST 'https://uat01.oms.fabric.inc/api/v2/order/returns' \
--header 'tenant-key: YOUR_ACCOUNT_ID_HERE' \
--header 'x-site-context: {"stage":"sandbox","account":"YOUR_ACCOUNT_ID_HERE","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": true,
    "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": 100.00,
            "fees": [
                {
                    "type": "tax",
                    "value": 34.56,
                    "quantity": 1,
                    "refundAmount": 10.4
                }
            ],
            "exchange": {
                "disableRefunding": true,
                "payment": {},
                "refund": {},
                "items": [
                    {
                        "itemId": "itemid-1",
                        "sku": "451009965461",
                        "itemUnitPrice": 0.00,
                        "quantity": 1,
                        "initiateReshipment": true
                    }
                ]
            }
        }
    ],
    "attributes": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
    }
}'