post:
  operationId: PostSwaps
  summary: Create a Swap
  description: >
    Create a Swap for an Order. This will also create a return and associate it
    with the swap. If a return shipping option is specified, the return will
    automatically be fulfilled.

    To complete the swap, you must use the Complete Cart endpoint passing it the
    ID of the swap's cart.


    An idempotency key will be generated if none is provided in the header
    `Idempotency-Key` and added to

    the response. If an error occurs during swap creation or the request is
    interrupted for any reason, the swap creation can be retried by passing the
    idempotency

    key in the `Idempotency-Key` header.
  externalDocs:
    description: How to create a swap
    url: https://docs.medusajs.com/modules/orders/storefront/create-swap
  requestBody:
    content:
      application/json:
        schema:
          $ref: ../components/schemas/StorePostSwapsReq.yaml
  x-codegen:
    method: create
  x-codeSamples:
    - lang: JavaScript
      label: JS Client
      source:
        $ref: ../code_samples/JavaScript/store_swaps/post.js
    - lang: Shell
      label: cURL
      source:
        $ref: ../code_samples/Shell/store_swaps/post.sh
  tags:
    - Swaps
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            $ref: ../components/schemas/StoreSwapsRes.yaml
    '400':
      $ref: ../components/responses/400_error.yaml
    '404':
      $ref: ../components/responses/not_found_error.yaml
    '409':
      $ref: ../components/responses/invalid_state_error.yaml
    '422':
      $ref: ../components/responses/invalid_request_error.yaml
    '500':
      $ref: ../components/responses/500_error.yaml