> ## Documentation Index > Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt > Use this file to discover all available pages before exploring further. # Submit return request by order identifier > Submits a return request for an order once it has been determined that the customer's return request is eligible. This endpoint processes the return request using the specified order identifier. **Note:** - Use this endpoint if you have the order number or external order ID. - If you only have an order number, set `orderIdType` to `order-number`. - If you only have an external order ID, set `orderIdType` to `order-external-id`. ## OpenAPI ````yaml orders.openapi post /orders/{orderIdType}/{orderIdValue}/actions/submit-return-request openapi: 3.0.1 info: contact: email: support@fabric.inc name: fabric Support Team description: >- fabric **Orders** API is a scalable multi-tenant service designed to streamline your order management process. Orders API is a REST and JSON driven interface enabling retailers to create orders directly from online Storefronts and Point-of-Sale systems, and serve as records of purchase transactions to permit retailers to operate against a standard schema with varied purchase channels.

fabric Orders API creates orders real time in the orders database, unifying the order data for users to streamline order lifecycle orchestration and customer service operations. It offers a range of features including the ability to create orders, get orders, update pickup details, and track orders, as well as search for existing orders. Also, the Orders API makes it easy to check eligibility of return, cancel, and exchange requests as well process them, if eligible. In addition, you can flag fraudulent orders based on due diligence, and either release them from hold or cancel them altogether. The appeasement feature helps you resolve any issues that may arise with an order and keep your customers happy.

license: name: fabric API License url: https://fabric.inc/api-license termsOfService: https://fabric.inc/terms-of-use title: fabric Orders API version: 3.0.0 x-audience: external-public servers: - description: Production url: https://api.fabric.inc/v3 security: - authorization: [] tags: - description: These endpoints authorize order payments. name: Payments - description: These endpoints help create appeasement requests. name: Appeasements - description: >- Credits are refunds to customers, often in the form of gift cards or credit notes, when customers have made payments with cash or a card that has subsequently expired. Credits are provided during order returns and appeasements. Use these endpoints to create and manage credits. name: Credits - description: >- These endpoints check eligibility of order cancellation requests and if eligible, processes order cancellation. name: Cancellations - description: These endpoints track orders. name: Tracking - description: >- These endpoints create orders, update pickup details (for BOPIS scenarios) and get order details. name: Orders - description: >- These endpoints check eligibility of order return or exchanges requests and, if eligible, processes order return or exchanges. name: Returns - description: These endpoints deal with potential fraud orders. name: Frauds externalDocs: description: Find out more about fabric Orders (also called OMS) url: https://developer.fabric.inc/v3/docs/orders-overview paths: /orders/{orderIdType}/{orderIdValue}/actions/submit-return-request: post: tags: - Returns summary: Submit return request by order identifier description: > Submits a return request for an order once it has been determined that the customer's return request is eligible. This endpoint processes the return request using the specified order identifier. **Note:** - Use this endpoint if you have the order number or external order ID. - If you only have an order number, set `orderIdType` to `order-number`. - If you only have an external order ID, set `orderIdType` to `order-external-id`. operationId: submitReturnRequestByOrderIdentifier parameters: - name: orderIdType in: path description: | The type of order identifier used to locate the order. Supported values: - `order-number` - `order-external-id` required: true schema: type: string enum: - order-number - order-external-id example: order-external-id - name: orderIdValue in: path description: The value of the specified order identifier. required: true schema: type: string example: bef5680-u1245678 - $ref: '#/components/parameters/xFabricTenantId' - $ref: '#/components/parameters/xFabricChannelId' - $ref: '#/components/parameters/xFabricRequestId' requestBody: content: application/json: schema: $ref: '#/components/schemas/orderReturnRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/returnOrderResponse' description: Return request accepted headers: x-fabric-request-id: $ref: '#/components/headers/xFabricRequestIdResponseHeader' '400': description: Bad request headers: x-fabric-request-id: $ref: '#/components/headers/xFabricRequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/errorResponse' example: type: CLIENT_ERROR errorCode: SERVICE-4003 message: 'Mandatory param(s): `requiredField1` is/are missing' errors: - type: CLIENT_ERROR errorCode: SERVICE-4002 message: Invalid value(s) specified for 'requiredField.field3' errors: [] context: service: orders endpoint: POST /v3/orders '401': description: Unauthorized headers: x-fabric-request-id: $ref: '#/components/headers/xFabricRequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/errorResponse' example: type: CLIENT_ERROR errorCode: SERVICE-4001 message: Unauthorized request errors: [] context: service: orders endpoint: POST /v3/orders/OrderId_12345 '404': content: application/json: schema: $ref: '#/components/schemas/errorResponse' example: '{"message": "Order not found, "type":"CLIENT_ERROR"" }' description: Not found headers: x-fabric-request-id: $ref: '#/components/headers/xFabricRequestIdResponseHeader' '500': description: Internal server error headers: x-fabric-request-id: $ref: '#/components/headers/xFabricRequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/errorResponse' example: type: SERVER_ERROR errorCode: SERVICE-5000 message: Internal server error errors: [] context: service: inventories endpoint: POST /v3/inventories/actions/find-by-geography components: parameters: xFabricTenantId: description: >- A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required. example: 5f328bf0b5f328bf0b5f328b in: header name: x-fabric-tenant-id required: true schema: type: string xFabricChannelId: description: >- x-fabric-channel-id identifies the sales channel where the API request is being made; primarily for multichannel use cases. The channel ids are 12 corresponding to US and 13 corresponding to Canada. The default channel id is 12. This field is required. example: '12' in: header name: x-fabric-channel-id required: true schema: type: string xFabricRequestId: description: Unique request ID example: 263e731c-45c8-11ed-b878-0242ac120002 in: header name: x-fabric-request-id required: false schema: type: string schemas: orderReturnRequest: description: Return request properties: attributes: description: >- Merchant-defined custom attributes. This is a placeholder for additional info in key: value pairs example: fraudCheckSessionId: 59f1d2b88de74aef96d3ec900ad548e0 fraudStatus: FRAUD_PASS type: object credits: items: $ref: '#/components/schemas/creditsRequest' type: array employeeId: description: Employee (ID or name) who initiated the request example: 62272e917b12209e68751d94 type: string fees: items: $ref: '#/components/schemas/returnFeeDetail' type: array isExchange: default: false description: >- **true:** Return includes one or more exchanges. **false:** Only returns, no exchange. example: false type: boolean items: description: Item details items: $ref: '#/components/schemas/returnItem' type: array reasonCode: description: Merchant-defined reason code for return example: Incorrect item type: string refunds: items: $ref: '#/components/schemas/returnFeeDetail' type: array returnedAt: description: Merchant-defined time for return (UTC) example: '2022-07-11T15:03:14.642Z' format: date-time type: string source: description: >- Merchant-defined source from where the return request was initiated. There are no pre-defined values; possible values are Customer Service Representative (CSR), point-of-sale (POS), etc. example: CSR type: string totalRefundAmount: description: Merchant-defined total refund amount example: 21.5 format: double type: number requestContext: $ref: '#/components/schemas/requestReferenceContextResource' description: Request reference context information required: - items - source type: object returnOrderResponse: description: An object containing the details of a returned order. properties: items: description: Item details items: $ref: '#/components/schemas/returnItemResponse' type: array refundStatus: description: Refund status enum: - REFUND_INITIATED - REFUND_SUCCESS - REFUND_FAILURE - REFUND_PENDING example: REFUND_INITIATED type: string totalRefundAmount: description: Merchant-defined total refund amount example: 21.5 format: double type: number totalRefundAmountInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array type: object errorResponse: description: Error response properties: errors: description: Errors items: $ref: '#/components/schemas/errorResponse' type: array message: description: Error message example: Bad request type: string type: description: Error type example: CLIENT_ERROR type: string type: object creditsRequest: description: Request for credits properties: amount: description: Credits amount example: 21.5 format: double type: number amountInCurrencies: description: > A list of amounts represented in different currencies. Each item includes a monetary value and its corresponding currency code, following the structure defined in the `amountInCurrency` schema. This field is used to represent multi-currency totals or balances. items: $ref: '#/components/schemas/amountInCurrency' type: array attributes: description: >- Merchant-defined custom attributes. This is a placeholder for additional info in key-value pairs. example: giftCardNumber: XlQZTmFDFtPFGMxJP6oiAqN3vo+qKZ type: object currency: description: Three-letter currency code as defined by ISO-4217 example: USD type: string employeeId: description: Employee (ID or name) who initiated a the credits request example: '12312232' type: string note: description: Note example: Credit request initiated type: string paymentCounter: description: >- A sequential or incremental counter associated with a payment for an order. Applicable in refund scenarios to identify the specific payment for refund. example: 1 format: int32 type: integer policyCode: description: >- Merchant-defined policy code, varies from merchant to merchant. If omitted, the default policy is used. example: RC1 type: string reasonCode: description: Reason code example: EC type: string source: description: Source of credits request example: CSR type: string subReasonCode: description: Subreason code example: ACC type: string type: description: Credit type. Currently, supports only Gift Card enum: - GIFT_CARD example: GIFT_CARD type: string required: - amount - currency - reasonCode - source - type type: object returnFeeDetail: description: An object containing return fee details. properties: amount: description: Merchant-defined return amount example: 34.56 format: double type: number amountInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array name: description: Fee name example: RETURN_FEE type: string reason: description: Merchant-defined return reason example: Return fee type: string type: description: Return fee type enum: - TAX - DISCOUNT - FEE - ITEM - ADJUSTMENT example: FEE type: string type: object returnItem: description: An object containing return details for an item. properties: attributes: description: >- Merchant-defined custom attributes. This is a placeholder for additional info in key-value pairs. example: fraudCheckSessionId: 59f1d2b88de74aef96d3ec900ad548e0 fraudStatus: FRAUD_PASS type: object exchange: $ref: '#/components/schemas/returnsExchangeData' fees: items: $ref: '#/components/schemas/returnFeeDetail' type: array isPolicyOverride: description: '**true:** Disable policy check. **false:** Enable the policy check.' example: true type: boolean orderLineItemId: description: Unique identifier for each item in order example: '1' type: string quantity: description: Returned quantity of the given item example: 1 format: int32 type: integer reasonCode: description: Reason code for return, varies from merchant to merchant. example: Incorrect order type: string refundAmount: description: Merchant-defined total refund amount example: 21.5 format: double type: number refundAmountInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array refunds: items: $ref: '#/components/schemas/returnFeeDetail' type: array returnAmountInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array returnType: description: Return type enum: - PENDING - PROCESSING - REJECTED - RECEIVED example: RECEIVED type: string scannedAt: description: Scanned time of return (UTC) example: '2022-07-11T15:03:14.642Z' format: date-time type: string shipmentId: description: 24-character system-generated shipment ID example: 62b37697c67b204dd18a7465 type: string shipmentLineId: description: Unique identifier for each item in the shipment example: '12' type: string subReasonCode: description: Sub-reason code for return, for another layer of classification example: Incorrect specification type: string required: - orderLineItemId - quantity - returnType - scannedAt - shipmentId - shipmentLineId type: object requestReferenceContextResource: type: object description: Request reference context information properties: id: type: string description: System-generated unique identifier (UUID format) example: a05b72dc-78d8-4ea4-90fc-2fe6a1fe1111 type: type: string requestId: type: string description: request id readOnly: true requestTime: type: string format: date-time description: System-generated order creation time example: '2022-04-12T09:30:31.198Z' attributes: type: object description: >- Merchant-defined custom attributes. This is a placeholder for additional info (in key: value pairs). example: attribute: 'N' someFlag: true returnItemResponse: description: Return details properties: lineItemId: description: >- Merchant-defined unique identifier for each item in an order. When omitted, fabric will generate it (in UUID format) during order creation. example: 62f3dfc438bcab1951be0a19 type: string policyCode: description: >- Merchant-defined policy code, varies from merchant to merchant. If omitted, the default policy is used. example: policyCode type: string refundAmount: description: Merchant-defined total refund amount example: 21.5 format: double type: number returnQuantity: description: Returned quantity of given item example: 2 format: int32 type: integer returnStatus: description: Return status enum: - VALID - POLICY_VIOLATION - PENDING - PROCESSING - REJECTED example: VALID type: string type: object amountInCurrency: description: Amount in currency object details. properties: amount: description: The amount displayed in the primary currency. example: 123.45 format: double type: number currency: description: Currency in ISO-4217 example: USD type: string group: description: >- A unique identifier for currencies. All calculations and invoicing are based on this identifier. For example, the `Shopper` group uses USD, while the `Retailer` group uses EUR. example: SHOPPER type: string required: - currency - group type: object returnsExchangeData: description: Item exchange and return details. properties: isRefundingDisabled: description: '**true:** Refund is disabled. **false:** Refund is enabled.' example: true type: boolean items: description: Item to be shipped in exchange for returned item items: $ref: '#/components/schemas/returnsExchangeItem' type: array refund: $ref: '#/components/schemas/orderRefund' required: - items type: object returnsExchangeItem: description: Item details for return or exchange properties: initiateReshipment: description: >- **true:** Proceed with reshipment immediately, do not wait for return. **false:** Proceed with the reshipment after return is successful. example: true type: boolean itemId: description: Unique identifier of item from fabric Products (PIM) service example: 1234 format: int32 type: integer itemUnitPrice: description: Item's unit price example: 10 format: double type: number itemUnitPriceInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array quantity: description: Number of items to be exchanged. example: 10 format: int32 type: integer sku: description: Stock Keeping Unit (SKU), unique identifier of item example: P1234 type: string required: - itemId - quantity - sku type: object orderRefund: description: Order refund properties: amount: description: Merchant-defined refund amount example: 34.56 format: double type: number amountInCurrencies: items: $ref: '#/components/schemas/amountInCurrency' type: array conversion: description: Conversion required for currency example: 1 format: double type: number currency: description: Three-letter currency code as defined by ISO-4217 example: USD type: string required: - amount type: object headers: xFabricRequestIdResponseHeader: description: Unique request ID example: 263e731c-45c8-11ed-b878-0242ac120002 required: false schema: type: string securitySchemes: authorization: bearerFormat: JWT scheme: bearer type: http ````