Skip to main content
Using the exchange functionality of fabric’s Orders service, the Customer Service Representatives (CSR) can exchange an order item. Exchange is essentially a return + a new item shipment, and this phase integrates the returns service with the exchange service. General Rules:
  • Exchange functionality doesn’t have a separate endpoint, and uses the return service 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 can’t be shipped due to being out of stock, but the item returned for the exchange is processed, then the amount for the returned line items must be refunded.
  • Refunding and payment due to the price difference between the original and replacement items aren’t handled by the returns or exchange service. This information must be sent by the requester during the pending return flow.
Workflow: The exchange functionality has two flows:

​
Exchange items are shipped when the return is received

  • The returnType parameter is set to Received
  • The exchange parameter is set to true
  • The initiateReshipment parameter is set to 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
    {
  "returnedAt": "2022-07-11T15:03:14.642Z",
  "isExchange": true
  "credits": [
    {
      "type": "GIFT_CARD",
      "source": "CSR",
      "amount": 21.5,
      "currency": "USD",
      "paymentCounter": 1,
      "attributes": {
        "giftCardNumber": "XlQZTmFDFtPFGMxJP6oiAqN3vo+qKZ"
      },
      "reasonCode": "EC",
      "subReasonCode": "ACC",
      "employeeId": "12312232",
      "note": "Credit request initiated",
      "policyCode": "RC1"
    }
  ],
  "employeeId": "62272e917b12209e68751d94",
  "source": "CSR",
  "totalRefundAmount": 21.5,
  "refunds": [
    {
      "type": "FEE",
      "name": "RETURN_FEE",
      "reason": "Return fee",
      "amount": 34.56
    }
  ],
  "reasonCode": "Incorrect item",
  "fees": [
    {
      "type": "FEE",
      "name": "RETURN_FEE",
      "reason": "Return fee",
      "amount": 34.56
    }
  ],
  "items": [
    {
      "returnType": "RECEIVED",
      "orderLineItemId": "1",
      "shipmentId": "62b37697c67b204dd18a7465",
      "shipmentLineId": "12",
      "quantity": 1,
      "scannedAt": "2022-07-11T15:03:14.642Z",
      "reasonCode": "Incorrect order",
      "subReasonCode": "Incorrect specification",
      "refundAmount": 21.5,
      "refunds": [
        {
          "type": "FEE",
          "name": "RETURN_FEE",
          "reason": "Return fee",
          "amount": 34.56
        }
      ],
      "fees": [
        {
          "type": "FEE",
          "name": "RETURN_FEE",
          "reason": "Return fee",
          "amount": 34.56
        }
      ],
      "exchange": {
        "refund": {
          "amount": 34.56,
          "currency": "USD",
          "conversion": 1
        },
        "items": [
          {
            "itemId": 1234,
            "sku": "P1234",
            "quantity": 10,
            "itemUnitPrice": 10,
            "initiateReshipment": true
          }
        ],
        "isRefundingDisabled": true
      },
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}

​
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.
  • The administrator 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
    {
  "returnedAt": "2022-07-11T15:03:14.642Z",
  "isExchange": true
  "credits": [
    {
      "type": "GIFT_CARD",
      "source": "CSR",
      "amount": 21.5,
      "currency": "USD",
      "paymentCounter": 1,
      "attributes": {
        "giftCardNumber": "XlQZTmFDFtPFGMxJP6oiAqN3vo+qKZ"
      },
      "reasonCode": "EC",
      "subReasonCode": "ACC",
      "employeeId": "12312232",
      "note": "Credit request initiated",
      "policyCode": "RC1"
    }
  ],
  "employeeId": "62272e917b12209e68751d94",
  "source": "CSR",
  "totalRefundAmount": 21.5,
  "refunds": [
    {
      "type": "FEE",
      "name": "RETURN_FEE",
      "reason": "Return fee",
      "amount": 34.56
    }
  ],
  "reasonCode": "Incorrect item",
  "fees": [
    {
      "type": "FEE",
      "name": "RETURN_FEE",
      "reason": "Return fee",
      "amount": 34.56
    }
  ],
  "items": [
    {
      "returnType": "RECEIVED",
      "orderLineItemId": "1",
      "shipmentId": "62b37697c67b204dd18a7465",
      "shipmentLineId": "12",
      "quantity": 1,
      "scannedAt": "2022-07-11T15:03:14.642Z",
      "reasonCode": "Incorrect order",
      "subReasonCode": "Incorrect specification",
      "refundAmount": 21.5,
      "refunds": [
        {
          "type": "FEE",
          "name": "RETURN_FEE",
          "reason": "Return fee",
          "amount": 34.56
        }
      ],
      "fees": [
        {
          "type": "FEE",
          "name": "RETURN_FEE",
          "reason": "Return fee",
          "amount": 34.56
        }
      ],
      "exchange": {
        "refund": {
          "amount": 34.56,
          "currency": "USD",
          "conversion": 1
        },
        "items": [
          {
            "itemId": 1234,
            "sku": "P1234",
            "quantity": 10,
            "itemUnitPrice": 10,
            "initiateReshipment": true
          }
        ],
        "isRefundingDisabled": true
      },
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}