An order or portion of an order is eligible for return if:

  • It’s fulfilled.
  • The items to be returned aren’t previously returned.
  • The item’s eligible property is set to false in check order return eligibility API response.
  • The item aligns with fabric’s return policy.

General Rules:

​
Initiate a return request 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 isn’t received at the distribution center:

  1. Set returnType to PENDING in the request payload while using the POST/v3/orders/{orderId}/actions/submit-return-request endpoint to create a return.
  • lineOrderStatus will be updated to RETURN_PENDING for the line item of an order ID. Merchants can get the order details, along with the order status, by calling the GET/v3/orders/{orderId} 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
  "returnedAt": "2022-07-11T15:03:14.642Z",
   "isExchange": false
  "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": "PENDING",
      "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
        }
      ],
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}

​
Item reaches the distribution center and is processed for return or reject

  • When an item reaches the distribution center, use the POST/v3/orders/{orderId}/actions/submit-return-request 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/v3/orders/{orderId} 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
  "returnedAt": "2022-07-11T15:03:14.642Z",
   "isExchange": false
  "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
        }
      ],
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}
  • If customer service agent rejects the return request for any reason, they must use the POST/v3/orders/{orderId}/actions/submit-return-request 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/v3/orders/{orderId} 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
  "returnedAt": "2022-07-11T15:03:14.642Z",
   "isExchange": false
  "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": "REJECTED",
      "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
        }
      ],
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}

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

  • Use POST/v3/orders/{orderId}/actions/submit-return-request 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://api.fabric.inc/v3/orders/orderId/actions/submit-return-request' \
--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 '{
  "returnedAt": "2022-07-11T15:03:14.642Z",
   "isExchange": false
  "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
        }
      ],
      "isPolicyOverride": true
    }
  ],
  "attributes": {
    "fraudStatus": "FRAUD_PASS",
    "fraudCheckSessionId": "59f1d2b88de74aef96d3ec900ad548e0"
  }
}

Was this page helpful?

Order ExchangeList of Webhook Events