SwapsResource

This class is used to send requests to Store Swap API Routes. All its method are available in the JS Client under the medusa.swaps property.

A swap is created by a customer or an admin to exchange an item with a new one. Creating a swap implicitely includes creating a return for the item being exchanged.

Related Guide: How to create a swap in a storefront

Methods

create

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 CartsResource.complete method 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.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.swaps.create({
  order_id,
  return_items: [
    {
      item_id,
      quantity: 1
    }
  ],
  additional_items: [
    {
      variant_id,
      quantity: 1
    }
  ]
})
.then(({ swap }) => {
  console.log(swap.id);
})

Parameters

payloadStorePostSwapsReqRequired

The data of the swap to be created.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreSwapsRes>Required

Resolves to the swap's details.

retrieveByCartId

Retrieve a Swap's details by the ID of its cart.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.swaps.retrieveByCartId(cartId)
.then(({ swap }) => {
  console.log(swap.id);
})

Parameters

cart_idstringRequired

The cart's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreSwapsRes>Required

Resolves to the swap's details.