Skip to main content
Skip to main content

SwapService

Handles swaps

Constructors​

constructor​

**new SwapService**(«destructured»)

Parameters​

__namedParametersInjectedPropsRequired

Properties​

__configModule__Record<string, unknown>
__container__anyRequired
__moduleDeclaration__Record<string, unknown>
cartService_CartServiceRequired
customShippingOptionService_CustomShippingOptionServiceRequired
eventBus_EventBusServiceRequired
fulfillmentService_FulfillmentServiceRequired
lineItemAdjustmentService_LineItemAdjustmentServiceRequired
lineItemService_LineItemServiceRequired
manager_EntityManagerRequired
orderService_OrderServiceRequired
paymentProviderService_PaymentProviderServiceRequired
productVariantInventoryService_ProductVariantInventoryServiceRequired
returnService_ReturnServiceRequired
shippingOptionService_ShippingOptionServiceRequired
swapRepository_Repository<Swap>Required
totalsService_TotalsServiceRequired
transactionManager_undefined | EntityManagerRequired
EventsobjectRequired
Events.CREATEDstringRequired

Default: "swap.created"

Events.FULFILLMENT_CREATEDstringRequired

Default: "swap.fulfillment_created"

Events.PAYMENT_CAPTUREDstringRequired

Default: "swap.payment_captured"

Events.PAYMENT_CAPTURE_FAILEDstringRequired

Default: "swap.payment_capture_failed"

Events.PAYMENT_COMPLETEDstringRequired

Default: "swap.payment_completed"

Events.PROCESS_REFUND_FAILEDstringRequired

Default: "swap.process_refund_failed"

Events.RECEIVEDstringRequired

Default: "swap.received"

Events.REFUND_PROCESSEDstringRequired

Default: "swap.refund_processed"

Events.SHIPMENT_CREATEDstringRequired

Default: "swap.shipment_created"

Accessors​

activeManager_​

Protected get**activeManager_**(): EntityManager

Returns​

EntityManager

EntityManagerEntityManagerRequired

Methods​

areReturnItemsValid​

Protected **areReturnItemsValid**(returnItems): Promise&#60;boolean&#62;

Parameters​

returnItemsWithRequiredProperty<Partial<ReturnItem>, "item_id">[]Required

Returns​

Promise<boolean>

PromisePromise<boolean>Required

atomicPhase_​

Protected **atomicPhase_**<TypeParameter TResult, TypeParameter TError>(work, isolationOrErrorHandler?, maybeErrorHandlerOrDontFail?): Promise&#60;TResult&#62;

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

TResultobjectRequired
TErrorobjectRequired

Parameters​

work(transactionManager: EntityManager) => Promise<TResult>Required
the transactional work to be done
isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>
the isolation level to be used for the work.
maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>
Potential error handler

Returns​

Promise<TResult>

PromisePromise<TResult>Required
the result of the transactional work

cancel​

**cancel**(swapId): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Cancels a given swap if possible. A swap can only be canceled if all related returns, fulfillments, and payments have been canceled. If a swap is associated with a refund, it cannot be canceled.

Parameters​

swapIdstringRequired
the id of the swap to cancel.

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the canceled swap.

cancelFulfillment​

**cancelFulfillment**(fulfillmentId): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Cancels a fulfillment (if related to a swap)

Parameters​

fulfillmentIdstringRequired
the ID of the fulfillment to cancel

Returns​

Promise<Swap>

PromisePromise<Swap>Required
updated swap

create​

**create**(order, returnItems, additionalItems?, returnShipping?, custom?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Creates a swap from an order, with given return items, additional items and an optional return shipping method.

Parameters​

orderOrderRequired
the order to base the swap off
returnItemsWithRequiredProperty<Partial<ReturnItem>, "item_id">[]Required
the items to return in the swap
additionalItemsPick<LineItem, "variant_id" | "quantity">[]
the items to send to the customer
returnShippingobject
an optional shipping method for returning the returnItems
returnShipping.option_idstringRequired
returnShipping.pricenumber
customobjectRequired
contains relevant custom information. This object may include no_notification which will disable sending notification when creating swap. If set, it overrules the attribute inherited from the order
custom.allow_backorderboolean
custom.idempotency_keystring
custom.location_idstring
custom.no_notificationboolean

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the newly created swap

createCart​

**createCart**(swapId, customShippingOptions?, context?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Creates a cart from the given swap. The cart can be used to pay for differences associated with the swap. The swap represented by the swapId must belong to the order. Fails if there is already a cart on the swap.

Parameters​

swapIdstringRequired
the id of the swap to create the cart from
customShippingOptions{ option_id: string ; price: number }[]Required
the shipping options

Default: []

contextobjectRequired

Default: {}

context.sales_channel_idstring

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the swap with its cart_id prop set to the id of the new cart.

createFulfillment​

**createFulfillment**(swapId, config?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Fulfills the additional items associated with the swap. Will call the fulfillment providers associated with the shipping methods.

Parameters​

swapIdstringRequired
the id of the swap to fulfill,
configCreateShipmentConfigRequired
optional configurations, includes optional metadata to attach to the shipment, and a no_notification flag.

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the updated swap with new status and fulfillments.

createShipment​

**createShipment**(swapId, fulfillmentId, trackingLinks?, config?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Marks a fulfillment as shipped and attaches tracking numbers.

Parameters​

swapIdstringRequired
the id of the swap that has been shipped.
fulfillmentIdstringRequired
the id of the specific fulfillment that has been shipped
trackingLinks{ tracking_number: string }[]
the tracking numbers associated with the shipment
configCreateShipmentConfigRequired
optional configurations, includes optional metadata to attach to the shipment, and a noNotification flag.

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the updated swap with new fulfillments and status.

deleteMetadata​

**deleteMetadata**(swapId, key): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Dedicated method to delete metadata for a swap.

Parameters​

swapIdstringRequired
the order to delete metadata from.
keystringRequired
key for metadata field

Returns​

Promise<Swap>

PromisePromise<Swap>Required
resolves to the updated result.

list​

**list**(selector, config?): Promise&#60;[Swap](/references/services/classes/Swap)[]&#62;

List swaps.

Parameters​

selectorSelector<Swap>Required
the query object for find
configFindConfig<Swap>Required
the configuration used to find the objects. contains relations, skip, and take.

Returns​

Promise<Swap[]>

PromisePromise<Swap[]>Required
the result of the find operation

listAndCount​

**listAndCount**(selector, config?): Promise&#60;[[Swap](/references/services/classes/Swap)[], number]&#62;

List swaps.

Parameters​

selectorSelector<Swap>Required
the query object for find
configFindConfig<Swap>Required
the configuration used to find the objects. contains relations, skip, and take.

Returns​

Promise<[Swap[], number]>

PromisePromise<[Swap[], number]>Required
the result of the find operation

processDifference​

**processDifference**(swapId): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Process difference for the requested swap.

Parameters​

swapIdstringRequired
id of a swap being processed

Returns​

Promise<Swap>

PromisePromise<Swap>Required
processed swap

registerCartCompletion​

**registerCartCompletion**(swapId): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Register a cart completion

Parameters​

swapIdstringRequired
The id of the swap

Returns​

Promise<Swap>

PromisePromise<Swap>Required
swap related to the cart

registerReceived​

**registerReceived**(id): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Registers the swap return items as received so that they cannot be used as a part of other swaps/returns.

Parameters​

idanyRequired
the id of the order with the swap.

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the resulting order

retrieve​

**retrieve**(swapId, config?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Retrieves a swap with the given id.

Parameters​

swapIdstringRequired
the id of the swap to retrieve
configOmit<FindConfig<Swap>, "select"> & { select?: string[] }Required
the configuration to retrieve the swap

Default: {}

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the swap

retrieveByCartId​

**retrieveByCartId**(cartId, relations?): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Retrieves a swap based on its associated cart id

Parameters​

cartIdstringRequired
the cart id that the swap's cart has
relationsundefined | string[]Required
the relations to retrieve swap

Default: []

Returns​

Promise<Swap>

PromisePromise<Swap>Required
the swap

shouldRetryTransaction_​

Protected **shouldRetryTransaction_**(err): boolean

Parameters​

errRecord<string, unknown> | { code: string }Required

Returns​

boolean

booleanboolean

transformQueryForCart​

Protected **transformQueryForCart**(config): [Omit](/references/services/types/Omit)&#60;[FindConfig](/references/services/interfaces/FindConfig)&#60;[Swap](/references/services/classes/Swap)&#62;, "select"&#62; & &#123; select?: string[] &#125; & &#123; cartRelations: undefined \| string[] ; cartSelects: undefined \| keyof [Cart](/references/services/classes/Cart)[] &#125;

Transform find config object for retrieval.

Parameters​

configOmit<FindConfig<Swap>, "select"> & { select?: string[] }Required
parsed swap find config

Returns​

Omit<FindConfig<Swap>, "select"> & { select?: string[] } & { cartRelations: undefined \| string[] ; cartSelects: undefined \| keyof [Cart](/references/services/classes/Cart)[] }

Omit&#60;FindConfig&#60;Swap&#62;, "select"&#62; & &#123; select?: string[] &#125; & &#123; cartRelations: undefined \| string[] ; cartSelects: undefined \| keyof Cart[] &#125;Omit<FindConfig<Swap>, "select"> & { select?: string[] } & { cartRelations: undefined \| string[] ; cartSelects: undefined \| keyof [Cart](/references/services/classes/Cart)[] }
transformed find swap config

update​

**update**(swapId, update): Promise&#60;[Swap](/references/services/classes/Swap)&#62;

Update the swap record.

Parameters​

swapIdstringRequired
id of a swap to update
updatePartial<Swap>Required
new data

Returns​

Promise<Swap>

PromisePromise<Swap>Required
updated swap record

withTransaction​

**withTransaction**(transactionManager?): [SwapService](/references/services/classes/SwapService)

Parameters​

transactionManagerEntityManager

Returns​

SwapService

SwapServiceSwapServiceRequired
Was this section helpful?
© 2023 Medusa, Inc. All rights reserved.