openapi: 3.0.1
info:
  title: Cart Actions Endpoints Returns API
  description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
  contact:
    name: Cart Support
    email: support.cnc@fabric.inc
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- description: These endpoints check eligibility of order return or exchanges requests and, if eligible, processes order return or exchanges.
  name: Returns
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 \ncustomer's return request is eligible.  \nThis endpoint processes the return request using the specified order identifier.  \n\n**Note:**  \n- Use this endpoint if you have the order number or external order ID.  \n- If you only have an order number, set `orderIdType` to `order-number`.  \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
      operationId: submitReturnRequestByOrderIdentifier
      parameters:
      - name: orderIdType
        in: path
        description: "The type of order identifier used to locate the order.  \nSupported values:  \n- `order-number`  \n- `order-external-id`\n"
        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':
          description: Return request accepted
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/returnOrderResponse'
        '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':
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example: '{"message": "Order not found, "type":"CLIENT_ERROR"" }'
        '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
  /orders/{orderIdType}/{orderIdValue}/actions/check-exchange-eligibility:
    post:
      tags:
      - Returns
      summary: Check Order Exchange Eligibility by Order Identifier
      description: "Determines whether an item or order is eligible for exchange.  \nCustomers may request an exchange due to size, fit, color, or style preferences.  \nThis endpoint verifies eligibility according to your defined business policies.  \n\nYou can also specify a `lineItemId` to check exchange eligibility for a specific \nitem. If omitted, eligibility is checked for each item in the order.  \n\n**Note:**  \n- Use this endpoint if you have the order number or external order ID.  \n- If you only have an order number, set `orderIdType` to `order-number`.  \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
      operationId: checkExchangeEligibilityByOrderIdentifier
      parameters:
      - name: orderIdType
        in: path
        description: "The type of order identifier used to locate the order.  \nSupported values:  \n- `order-number`  \n- `order-external-id`\n"
        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
      - name: policyName
        in: query
        description: "The merchant-defined exchange policy to apply.  \nIf omitted, the default policy is used.\n"
        required: false
        schema:
          type: string
        example: RETURNS_POLICY_1
      - name: lineItemId
        in: query
        description: "A single line item ID.  \n- If specified, eligibility is checked only for that item.  \n- If omitted, eligibility is checked for each item in the order.\n"
        required: false
        schema:
          type: string
        example: 62f3dfc438bcab1951be0a19
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
        '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':
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                message: Order with <orderId> is not found
                type: CLIENT_ERROR
        '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
  /orders/{orderIdType}/{orderIdValue}/actions/check-return-eligibility:
    post:
      tags:
      - Returns
      summary: Check Return Eligibility by Order Identifier
      description: "Determines whether one or more items in an order are eligible for return.  \nCustomers may request a return because items did not meet expectations or \nthey simply changed their mind.  \n\nThis endpoint verifies eligibility according to your defined return policies.  \nYou can also specify a `lineItemId` to check return eligibility for a specific \nitem. If omitted, eligibility is checked for each item in the order.  \n\n**Note:**  \n- Use this endpoint if you have the order number or external order ID.  \n- If you only have an order number, set `orderIdType` to `order-number`.  \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
      operationId: checkReturnEligibilityByOrderIdentifier
      parameters:
      - name: orderIdType
        in: path
        description: "The type of order identifier used to locate the order.  \nSupported values:  \n- `order-number`  \n- `order-external-id`\n"
        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
      - name: policyName
        in: query
        description: "The merchant-defined return policy to apply.  \nIf omitted, the default policy is used.\n"
        required: false
        schema:
          type: string
        example: RETURNS_POLICY_1
      - name: lineItemId
        in: query
        description: "A single line item ID.  \n- If specified, eligibility is checked only for that item.  \n- If omitted, eligibility is checked for each item in the order.\n"
        required: false
        schema:
          type: string
        example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
        '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':
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                message: Order not found
                type: CLIENT_ERROR
        '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
  /orders/order-number/{orderNumber}/actions/check-exchange-eligibility:
    post:
      description: "Determines whether an order or specific items within an order are eligible for exchange.  \nCustomers may request an exchange due to size, fit, color, or style preferences.  \nThis endpoint checks exchange eligibility using the **order number**.  \n\nYou can also specify a `lineItemId` to check eligibility for a specific item.  \nIf omitted, eligibility is checked for each item in the order.  \n\n**Note:**  \n- Use this endpoint only if you have the order number.  \n- If you have an order ID instead, use the identifier-based endpoint:  \n  `POST /orders/{orderIdType}/{orderIdValue}/actions/check-exchange-eligibility`.\n"
      operationId: getOrderExchangeEligibilityByOrderNumber
      parameters:
      - description: Merchant-defined order identifier
        example: Order-320000001
        in: path
        name: orderNumber
        required: true
        schema:
          type: string
      - description: Merchant-defined exchange policy. When omitted, the default policy is considered.
        example: RETURNS_POLICY_1
        in: query
        name: policyName
        required: false
        schema:
          type: string
      - description: Line item ID. If specified, gets exchange eligibility of the given line item. If omitted, gets exchange eligibility of each item in the order.
        example: 62f3dfc438bcab1951be0a19
        in: query
        name: lineItemId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Order with <orderId> is not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Get Order Exchange Eligibility by Order Number
      tags:
      - Returns
  /orders/order-number/{orderNumber}/actions/check-return-eligibility:
    post:
      description: "Determines whether one or more items in an order are eligible for return.  \nCustomers may request a return if items do not meet expectations or if they \nhave simply changed their mind.  \nThis endpoint checks return eligibility using the **order number**.  \n\nYou can also specify a `lineItemId` to check eligibility for a specific item.  \nIf omitted, eligibility is checked for each item in the order.  \n\n**Note:**  \n- Use this endpoint only if you have the order number.  \n- If you have an order ID instead, use the identifier-based endpoint:  \n  `POST /orders/{orderIdType}/{orderIdValue}/actions/check-return-eligibility`.\n"
      operationId: getOrderReturnsEligibilityByOrderNumber
      parameters:
      - description: Merchant-defined order identifier
        example: Order-320000001
        in: path
        name: orderNumber
        required: true
        schema:
          type: string
      - description: Merchant-defined return policy. When omitted, the default policy is considered.
        example: RETURNS_POLICY_1
        in: query
        name: policyName
        required: false
        schema:
          type: string
      - description: Line item ID. If specified, you'll get the return eligibility of the given line item ID. If omitted, you'll get the return eligibility of each item in the order.
        example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
        in: query
        name: lineItemId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Order not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Get Return Eligibility by Order Number
      tags:
      - Returns
  /orders/order-number/{orderNumber}/actions/submit-return-request:
    post:
      description: 'When the customers return request is determined to be eligible, this endpoint is used to process the return request. <p> **Note**: If you do not have the order number, but have order ID, use Return order by order ID endpoint - `POST /orders/{orderId}/actions/submit-return-request`.</p>'
      operationId: returnsOrderByOrderNumber
      parameters:
      - description: Merchant-defined order identifier
        example: Order-20000001
        in: path
        name: orderNumber
        required: true
        schema:
          type: string
      - $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':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example: '{"message": "Order not found, "type":"CLIENT_ERROR"" }'
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Order Return by Order Number
      tags:
      - Returns
  /orders/{orderId}/actions/check-exchange-eligibility:
    post:
      description: 'Customers may want exchange an item because of size, color, or style preferences. Before processing exchange, its crucial to verify whether the item is eligible for exchange as per your policy. <p> This endpoint gets the eligibility of exchange request by order number. You can additionally specify `lineItemId` to get eligibility of a specific item.</p> <p> **Note**: If you do not have the order ID, but have the order number, use the order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/check-exchange-eligibility`.</p>'
      operationId: getOrderExchangeEligibilityByOrderId
      parameters:
      - description: 24-character system-generated order ID returned in the response of Create Order - `POST /orders` endpoint.
        example: 5349b4ddd2781d08c09890f4
        in: path
        name: orderId
        required: true
        schema:
          type: string
      - description: Merchant-defined exchange policy. When omitted, the default policy is considered.
        example: RETURNS_POLICY_1
        in: query
        name: policyName
        required: false
        schema:
          type: string
      - description: Line item ID. If specified, gets exchange eligibility of the given line item ID. If omitted, gets exchange eligibility of each item in the order.
        example: 62f3dfc438bcab1951be0a19
        in: query
        name: lineItemId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Order with orderId is not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Get Order Exchange Eligibility by Order ID
      tags:
      - Returns
  /orders/{orderId}/actions/check-return-eligibility:
    post:
      description: "Determines whether one or more items in an order are eligible for return.  \nCustomers may request a return if items do not meet expectations or if they \nhave simply changed their mind.  \n\nThis endpoint checks return eligibility using the **order ID**.  \nYou can also specify a `lineItemId` to check eligibility for a specific item.  \nIf omitted, eligibility is checked for each item in the order.  \n\n**Note:**  \n- Use this endpoint only if you have the order ID.  \n- If you have an order number instead, use the order number–based endpoint:  \n  `POST /orders/order-number/{orderNumber}/actions/check-return-eligibility`.\n"
      operationId: getOrderReturnsEligibilityByOrderId
      parameters:
      - description: 24-character system-generated order ID returned in the response of Create Order - `POST /orders` endpoint.
        example: 5349b4ddd2781d08c09890f4
        in: path
        name: orderId
        required: true
        schema:
          type: string
      - description: Merchant-defined return policy. When omitted, the default policy is considered.
        example: RETURNS_POLICY_1
        in: query
        name: policyName
        required: false
        schema:
          type: string
      - description: Line item ID. If specified, gets the return eligibility of the given line item ID. If omitted, gets the return eligibility of each item in the order.
        example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
        in: query
        name: lineItemId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligibilityResponse'
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '400':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Order not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Get Eligibility of Returns for Items in an Order by Order ID
      tags:
      - Returns
  /orders/{orderId}/actions/submit-return-request:
    post:
      description: 'When customers return request is found to be eligible, this endpoint submits the return request by order ID. <p> **Note**: If you do not have order ID, use the corresponding order number-based endpoint- `POST /orders/order-number/{orderNumber}/actions/submit-return-request`.</p>'
      operationId: returnsOrderByOrderId
      parameters:
      - description: 24-character system-generated order ID returned in the response of Create Order - `POST /orders` endpoint.
        in: path
        name: orderId
        required: true
        schema:
          type: string
      - $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':
          content:
            application/json:
              example:
                errors:
                - message: Invalid request
                  type: CLIENT_ERROR
                message: Bad request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '401':
          content:
            application/json:
              example:
                message: Unauthorized request
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '404':
          content:
            application/json:
              example:
                message: Order not found
                type: CLIENT_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
        '500':
          content:
            application/json:
              example:
                message: Internal server error
                type: SERVER_ERROR
              schema:
                $ref: '#/components/schemas/errorResponse'
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponseHeader'
      summary: Order Return by Order ID
      tags:
      - Returns
components:
  schemas:
    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
    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
    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
    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
    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
    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
    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
    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
    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.  \nEach item includes a monetary value and its corresponding currency code,  \nfollowing the structure defined in the `amountInCurrency` schema.  \nThis field is used to represent multi-currency totals or balances.\n"
          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
    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
    policyFeeResource:
      description: Policy fee
      properties:
        amount:
          description: Fee applicable for the policy
          example: 33.9
          format: double
          type: number
        amountInCurrencies:
          items:
            $ref: '#/components/schemas/amountInCurrency'
          type: array
        currency:
          description: Three-letter currency code as defined by ISO-4217
          example: USD
          type: string
        platinumFee:
          description: Fees applicable for return, cancellation, or exchange of an item as per the policy
          example: 33.9
          format: double
          type: number
      type: object
    eligibilityResponse:
      description: Eligibility details object.
      properties:
        eligibleReasonCodes:
          description: Reason codes for returns
          items:
            $ref: '#/components/schemas/reasonCodeAndDescription'
          type: array
        fees:
          description: Fee details
          items:
            $ref: '#/components/schemas/policyFeeResource'
          type: array
        items:
          description: Item's eligibility for return, cancellation, or exchange
          items:
            $ref: '#/components/schemas/itemEligibilityResource'
          type: array
        orderId:
          description: 24-character system-generated order ID
          example: 62f3982438bcab1951be0a19
          type: string
        period:
          description: Return, exchange or cancellation window as per merchant policy
          example: 30D00H00M
          type: string
        policyType:
          description: Policy type that determines eligibility of exchange, return, or cancellation. If omitted, the default policy is considered.
          example: Company Policy 2023
          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
    itemEligibilityResource:
      description: Item's eligibility for return, cancellation, or exchange
      properties:
        eligibleQuantity:
          description: Quantity of the given item eligible for return, cancellation, or exchange
          example: 10
          format: int32
          type: integer
        isEligible:
          description: 'true: Item is eligible for return or exchange  false: Item is not eligible for return or exchange'
          example: true
          type: boolean
        lineItemId:
          description: Merchant-defined unique identifier for each item in an order. When omitted, fabric will generate it during order creation, in UUID format.
          example: 62f3dfc438bcab1951be0a19
          type: string
        sku:
          description: Stock keeping unit (SKU), unique identifier of item
          example: P1234
          type: string
      type: object
    reasonCodeAndDescription:
      description: Return or exchange reason
      properties:
        code:
          description: Reason code for return, cancellation, or exchange. Values are configurable as per requirement.
          example: 1DMG
          type: string
        description:
          description: Brief description for the return `code`
          example: Damaged
          type: string
      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
  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
    xFabricRequestId:
      description: Unique request ID
      example: 263e731c-45c8-11ed-b878-0242ac120002
      in: header
      name: x-fabric-request-id
      required: false
      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
  headers:
    xFabricRequestIdResponseHeader:
      description: Unique request ID
      example: 263e731c-45c8-11ed-b878-0242ac120002
      required: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This is the authorization token used to authenticate the request. You must pass the access token generated from the system app. For more information, see the [Making your first API request](/v3/api-reference/getting-started/getting-started-with-fabric-apis#procedure) section.

        '